Company Agents owns a single directory on disk: the instance home. Everything else (runs, workspaces, backups, secrets, the database, integration state) lives under it in a predictable layout. This guide shows the layout and how to move each piece when you need to.

​
The instance home

The default instance home is: 
~/.company-agents/instances/default/
You can override it: 
COMPANY_AGENTS_HOME=/srv/company-agents/instances/default
The orchestrator creates the directory and all required sub-directories on first start.

​
The full layout

~/.company-agents/
├── instances/
│   └── default/
│       ├── db/                   # PGlite data dir (if using PGlite)
│       ├── data/
│       │   ├── storage/          # user-uploaded files, images, brief docs
│       │   └── backups/          # scheduled and manual backups
│       ├── secrets/
│       │   └── master.key        # the master encryption key
│       ├── runs/
│       │   ├── run_a1b2c3.../   # retained run workspaces
│       │   └── run_d4e5f6.../
│       ├── logs/                 # orchestrator and service logs
│       └── config.json           # instance-level config
│
└── runtime-services/
    ├── run_a1b2c3.../            # per-run runtime service state
    ├── run_d4e5f6.../
    └── shared/                   # pool-scoped service state

​
Each directory, in order

​
db/

The database. Either PGlite data files or, if you are using real Postgres, an empty directory. See database for the details.

​
data/storage/

User-uploaded assets. Logos, reference documents, image inputs, anything a human uploads through the dashboard or an agent writes through upload_asset. Not workspace files; those live under runs/. File layout: 
data/storage/
├── companies/<company-id>/
│   ├── logos/
│   ├── docs/
│   └── assets/
This can grow large. If you are tight on disk, move it with: 
STORAGE_PATH=/mnt/big-disk/company-agents/storage

​
data/backups/

Scheduled and manual backups (see Settings → Storage → Backups). Each backup is a .tar.gz that contains the database dump, the secrets bundle (if opted in), and the audit trail export. Retention is configurable. Default is “keep the last 7 daily backups and the last 4 weekly backups.” Move elsewhere with: 
BACKUP_PATH=/mnt/backup-disk/company-agents/backups
We recommend keeping backups on a different disk or a different host than the live data.

​
secrets/master.key

The 32-byte AES-256 master key. Everything in the secrets table in the database is encrypted with this key. See secrets for the full story. Enforced permissions: 0600. The orchestrator refuses to start if the file is readable by anyone but the owner.

​
runs/

Retained run workspaces. Each sub-directory is one run’s workspace, preserved because the run failed, was explicitly kept with --keep, or has an open audit trail entry. Workspace internals: 
runs/run_a1b2c3.../
├── .git/                         # git history of the run
├── .run/                         # checkpoints, local cache
├── .company-agents/
│   ├── task.json
│   ├── parent.json               # if this is a sub-task
│   ├── memory/                   # scoped memory snapshots
│   ├── context/                  # fetched inputs
│   └── budget.json               # current envelope state
├── src/, ...                     # the agent's actual working tree
Non-retained runs are deleted when the run ends successfully. See execution workspaces and runtime services for the full retention rules.

​
logs/

Orchestrator, MCP server, and adapter logs. Rotated daily, compressed after rotation, kept for 30 days by default. Configure with: 
LOG_PATH=/var/log/company-agents
LOG_RETENTION_DAYS=30

​
config.json

Instance-level config that is not secret: default adapter, default fiscal period, default budget split, etc. Set on first install, editable via the dashboard or by hand.

​
runtime-services/

Separate from instances/. Runtime services live here because they are the agent’s environment, not the agent’s writable state. See the execution workspaces guide for why the split matters. Per-run services are cleaned up when the run ends. Pool-scoped services (crawlers, image sourcers, anything expensive to start) live under shared/ and stay running across runs. Move this directory with: 
RUNTIME_SERVICES_PATH=/mnt/fast-disk/runtime-services
We recommend putting runtime services on a fast disk (SSD or NVMe). Crawl caches and image caches benefit measurably.

​
Moving the whole thing

To move an entire instance to a new location:
  1. Stop the orchestrator
  2. cp -a ~/.company-agents/instances/default/ /new/path/
  3. cp -a ~/.company-agents/runtime-services/ /new/path/runtime-services
  4. Set COMPANY_AGENTS_HOME=/new/path/ and the relevant sub-path env vars
  5. Start the orchestrator
  6. Verify: dashboard loads, companies are present, secrets decrypt, runs list is intact
  7. Delete the old location only after at least one successful day of operation on the new one
No database migration is needed (the PGlite files move with the directory). If you are using real Postgres, the database is not on disk in this layout so you do not need to touch it.

​
Disk usage estimates

Rough numbers for a small team running a single company:
  • Database (PGlite): 100 MB to 1 GB
  • Retained runs: 50 MB to 500 MB per retained run
  • Runtime services: up to a few GB for caches and crawl data
  • Backups: roughly 2x the live database, times the retention count
  • Logs: a few hundred MB per month, compressed
A df -h on the instance home every week is a healthy habit.

​
Next