Deployment modes

Company Agents runs in four shapes. The overview introduced them; this guide is the reference. Use it when you need to decide which shape you are on, or when you need to know what changes if you move from one to another.

​

Shape 1: Desktop

What runs where: one machine runs everything. The orchestrator, the PGlite database, the runtime services, and the agents all share a single process tree on your laptop or workstation. The dashboard is served at http://localhost:3101 and nothing is exposed beyond loopback. Database: PGlite, embedded in the orchestrator process, writing to ~/.company-agents/instances/default/db/. Secrets: encrypted with the master key at ~/.company-agents/instances/default/secrets/master.key. Auth: none. Localhost is trusted. Capacity: a few hundred concurrent tasks before PGlite becomes the bottleneck. Upgrade to real Postgres before you hit that wall. When to pick it: you are the only user and you want the lowest-friction install. When to move on: when you want another device to reach the dashboard (go to Private network) or when PGlite starts feeling slow on large runs (go to Docker single-host with real Postgres).

​

Shape 2: Private network

What runs where: same as Desktop. The only change is that the dashboard binds to the Tailscale interface (or a private interface of your choice) instead of loopback. Database: PGlite, unchanged. Secrets: unchanged. Auth: Tailscale handles device auth. You can optionally add a password layer inside the dashboard if you want belt-and-suspenders. Capacity: same as Desktop. When to pick it: you want to approve agents from your phone while the orchestrator runs on your workstation. When to move on: when other humans need their own inbox (go to Docker single-host multi-user) or when you outgrow PGlite. See Tailscale private access for the concrete setup.

​

Shape 3: Docker single-host

What runs where: one server runs the orchestrator and the database inside Docker. Agents-as-binaries (Claude Code, Codex, Gemini) run on the same host but outside the container. The dashboard is exposed over HTTPS via your own reverse proxy or Tailscale. Database: real Postgres 16, in a separate container. Drizzle migrations run on start. Secrets: master key mounted into the orchestrator container as a file, not as an env var (env vars leak into logs). Auth: dashboard login required. Each teammate gets their own account. Capacity: up to a few thousand concurrent tasks, depending on hardware. The ceiling is agents, not the orchestrator. When to pick it: a small team (2 to 10 humans) wants to share one company. You have a box you trust and want a clean, restartable install. When to move on: when you want agents to run on different hardware than the orchestrator (go to Multi-host). See Docker for the concrete setup.

​

Shape 4: Multi-host

What runs where:

• Control node: orchestrator, database, MCP server, dashboard. One node, or two for failover.
• Worker nodes: run adapters that launch agents. Each worker node has its own runtime services directory. Workers can be specialized (GPU nodes for image agents, CPU for everything else).
• All nodes: share the same Postgres and the same secret store.

Database: real Postgres, usually a managed service (RDS, Cloud SQL, Neon) or your own HA cluster. Secrets: pulled from a secret manager at startup (Vault, AWS Secrets Manager, whatever you use), not from a file on disk. Auth: dashboard login, plus optional SSO. Capacity: depends on how many workers you run. The orchestrator can drive several thousand concurrent agent processes distributed across workers. When to pick it: you have real fleet management needs. Most small teams never do. When to move on: multi-host is the top of the ladder. If you are outgrowing it you are in “build your own scheduler on top of our API” territory.

​

What changes between shapes

As you move up the ladder, a few things change materially:

​

Migrating between shapes

​

Desktop → Private network

Trivial. Change DASHBOARD_HOST to 0.0.0.0 and run tailscale cert. No data migration needed.

​

Desktop → Docker single-host

1. Export the current company or companies as .ca-archive files from the desktop app
2. Spin up the Docker setup on the new host
3. Import the archives into the new install

No in-place migration; you move the data by import/export. Keep the old desktop install running until you have verified the new install has everything.

​

Docker single-host → Multi-host

This is a real migration. Steps:

1. Move the database from the compose Postgres to your managed Postgres (use pg_dump/pg_restore)
2. Move the secrets from the on-disk master key to your secret manager
3. Redeploy the orchestrator against the new database and secret store
4. Add worker nodes one at a time
5. Cut over the dashboard DNS

Most teams do not do this themselves; if you are going down this path, open an issue and we will help.

​

Next

• Database for the database layer in each shape
• Secrets for how master key management changes between shapes
• Storage for the on-disk layout details
• Environment variables for the full list of tunables