When an agent runs, it needs two things on disk: a workspace to do its work in, and runtime services to call. Company Agents separates these on purpose, and the separation is the first thing to understand before you run anything that writes files or spins up processes.

​
Execution workspaces

An execution workspace is the directory where a specific workflow run happens. Every run gets its own fresh workspace, created fresh at the start and torn down when the run ends (unless the run is marked for retention). A workspace is scoped to exactly one run. It contains:
  • A git-initialized working tree where the agent edits files
  • A .run/ directory holding the run’s checkpoints and local cache
  • A .company-agents/ subdirectory with the task context, the agent memory snapshots for this scope, and the current budget state
  • Any files the workflow fetches as inputs (brief documents, reference material, crawl output)
Workspaces live at ~/.company-agents/instances/default/runs/{run-id}/ by default. You can override the base directory with the --runs-dir flag at run time, or change the default under Settings → Storage.

​
Why the fresh-workspace design

Agents mutate state. They write files, install packages, edit configs, create temporary scratch directories. If two runs shared a workspace, one run’s mutations would leak into the next. The fresh-per-run model means:
  • Every run starts from a known-good state
  • You can run ten workflows in parallel without them stepping on each other
  • Killing a run is as simple as killing the workspace
  • Reproducing a past run is possible as long as its workspace is preserved (see retention below)

​
Workspace retention

By default, a workspace is deleted when its run ends successfully. You can keep it around under three conditions:
  1. On failure: workspaces from failed runs are preserved for 7 days by default so you can debug.
  2. On demand: mark a run --keep at start time and its workspace will be preserved indefinitely.
  3. On audit: workspaces referenced by an open audit trail entry (for example, a workspace that produced a shipped artifact) are kept until the audit entry is purged.
You can configure retention under Settings → Storage → Workspace retention.

​
Git inside the workspace

Every workspace is a git repo. Every commit the agent makes lands in the workspace’s local git history. When the run ships, you can:
  • Export the git history as a patch
  • Push it to a remote
  • Inspect the diff between any two commits
  • Roll the workspace back to a prior commit and resume from there
For workflows that target a real git repository (not a fresh workspace), the workspace is a git clone of the target, and commits are pushed to a feature branch at the end of the run rather than living only in the workspace.

​
Runtime services

Runtime services are the background processes an agent can call on while it is running. They are launched by the orchestrator at run start, live for the duration of the run, and are torn down at the end. Typical runtime services:
  • A local MCP server exposing the tools the agent has been granted for this run
  • A filesystem sandbox enforcing the workspace boundary
  • A subprocess manager for anything the agent spawns
  • A web preview for UI agents that need to see their work rendered
  • A crawler for agents that need to fetch web pages
  • An image sourcer for agents that generate visuals
Runtime services live at ~/.company-agents/runtime-services/{run-id}/. Each service gets its own subdirectory for its local state, logs, and configuration.

​
Why separate services from workspaces

The workspace is the agent’s writable scratch pad. Runtime services are the agent’s environment. Keeping them separate means:
  • An agent cannot accidentally corrupt its tooling by writing to the wrong place
  • You can inspect service logs without wading through the agent’s own files
  • Restarting a single service does not reset the agent’s workspace
  • Different runs can share the same runtime service process pool (for expensive services like a crawler) without sharing files

​
Service lifecycle

When a run starts:
  1. The orchestrator reads the workflow definition
  2. For each required service, the orchestrator either starts a new instance or reuses an existing one from the pool
  3. The service’s endpoint (unix socket or loopback port) is registered with the agent’s tool proxy
  4. The agent makes calls against the proxy, the proxy forwards to the service, and the response comes back
When the run ends:
  1. The orchestrator flushes any buffered service logs to the audit trail
  2. Services marked as run-scoped are terminated
  3. Services marked as pool-scoped remain running for the next run
  4. The workspace is torn down (or preserved, per retention rules)

​
Where it all sits on disk

~/.company-agents/
├── instances/default/
│   ├── db/                      # PGlite database
│   ├── data/
│   │   ├── storage/             # User-uploaded assets
│   │   └── backups/             # Database backups
│   ├── secrets/
│   │   └── master.key           # Master encryption key
│   ├── runs/
│   │   ├── run-2026-04-11-…/    # One run's workspace
│   │   └── run-2026-04-11-…/
│   └── config.json              # Instance-level config
│
└── runtime-services/
    ├── run-2026-04-11-…/        # Per-run service state
    └── shared/                  # Pool-scoped service state
You rarely need to touch this layout by hand. The CLI and UI expose everything you would usually want to do, and direct filesystem access is the wrong layer to poke at for anything other than debugging.

​
Next