FILES WITH
REAL ROOTS.

Two layers, one file

Each tracked file has bytes in the configured storage backend and durable metadata in PostgreSQL: title, filename, content type, ownership, customer or project scope, visibility, checksums, and lifecycle information. The database answers who can see a file and what it belongs to; the storage tree makes the file usable by ordinary tools.

Real filesystem folders

From version 0.8.0, logical folders are mirrored into the filesystem layout. Existing artifact IDs and API routes remain stable. The additive migration records mirror state, while the reconciliation command safely moves legacy flat objects into their logical paths.

# Preview changes first
docker compose exec app npm run storage:reconcile

# Apply after reviewing the report
docker compose exec app npm run storage:reconcile -- --apply

Run reconciliation after the database migration and before enabling a Drive mirror. It is idempotent: rerunning it verifies completed work instead of duplicating files.

Create and edit files in EmperorClaw

Storage can create empty DOCX, XLSX, CSV, Markdown, JSON, and text files. DOCX and XLSX editors are loaded only when needed and save through the same artifact replacement flow, preserving metadata and updating checksums. CSV, Markdown, JSON, and text use lightweight editors.

Rename, move, and delete files through EmperorClaw so the database, local path, and Drive mirror change together. Emperor-originated deletions are queued durably and sent to Google Drive Trash. Deleting an item directly in Drive never deletes the canonical EmperorClaw copy.

Optional Google Drive mirroring

The supported self-hosted pattern uses the optional drive Compose profile. An rclone sidecar mounts the same storage volume as the application and synchronizes a dedicated Drive folder frequently. No Google OAuth code runs inside EmperorClaw.

# Configure the dedicated Drive remote once
docker compose --profile drive-setup run --rm drive-config

# Start the application and mirror
docker compose --profile drive up -d

Use a dedicated Google OAuth client and a dedicated remote folder. Do not point the mirror at an entire personal Drive. The exact environment keys and OAuth flow are documented in the repository’s self-hosting guide.

Files added directly in Drive

An edited tracked file synchronizes back and appears updated in EmperorClaw. A brand-new file uploaded directly to Drive appears as an untracked candidate: visible in Storage with a question mark, but not yet indexed or exposed through artifact APIs.

Choose Add metadata, confirm its name, folder, customer or project, visibility, and other metadata, then import it. Until that explicit step, agents should not treat the file as trusted company context. If the item is a stale copy left by an older sidecar, choose Remove from storage and Drive; EmperorClaw refuses the action when the path contains active tracked data.

Conflicts are not version control

A filesystem mirror is convenient for editing and an additional copy, but it is not a complete backup strategy. Simultaneous edits can create conflicts and large files take time to transfer. EmperorClaw deletions reach Drive Trash, which is recoverable until the Trash is emptied. Keep database and storage backups together and test restoration.

• Edit a tracked file in one place at a time.
• Keep the sync interval short, but allow transfers to finish.
• Review untracked candidates before import.
• Back up PostgreSQL and the storage volume as one recovery unit.
• Pause mirroring during major storage maintenance.