Skip to content

Concept Relationships

This page answers one question:

How do these concepts fit together on one map?

If you remember only one sentence, use this:

workspace is the logical project boundary, sandbox is the execution host boundary, and worker is the execution role running inside that host.

You need to read the system through two chains at the same time.

Agent Engine -> Workspace -> Session -> Run

This chain answers:

  • which project is active
  • which capabilities that project declares
  • which workspace a session belongs to
  • how one execution becomes a run

Agent Engine -> Worker -> Sandbox -> Active Workspace Copy

This chain answers:

  • who executes
  • where execution happens
  • which active execution copy receives file and command operations
flowchart TD
A["Agent Engine"] --> B["Workspace"]
B --> C["Session"]
C --> D["Run"]
A --> E["Worker"]
E --> F["Sandbox"]
F --> G["Active Workspace Copy"]
B -. "materialize into active copy" .-> G
D -. "executed by owner worker" .-> E
ConceptWhat it isWhat it is not
Agent EngineThe scheduling, execution, recovery, audit, and API / SSE systemNot a single agent definition
WorkspaceThe project, capability-discovery, and session-ownership boundaryNot an execution host
SessionA continuous collaboration context inside one workspaceNot an execution thread
RunOne model inference and tool loopNot a long-lived container
WorkerThe role that executes runsNot the project itself
SandboxThe filesystem and process host where a worker runsNot another name for workspace
Active Workspace CopyThe active execution copy of a workspace inside a host, meaning the actual files used for reads, writes, and commands inside the sandboxNot a separate workspace kind
RuntimeThe initialization source used when creating a workspaceNot the active execution copy
SpecThe user-authored extension layer added to a runtimeNot the whole runtime structure
ComparisonWorkspaceSandbox
FocusProject and capabilitiesHost and execution environment
Main question”Which project is this?""Where is it running?”
Typical contentsAGENTS.md, agents, models, skills, hooksFilesystem, processes, commands, mount points
API noun/workspaces/sandboxes

Conclusion:

  • workspace defines project identity and capability set
  • sandbox defines filesystem and process context for the active copy
ComparisonWorkspaceRuntime
FocusCurrent projectInitialization source
Used whenRunning, discovering capabilities, executing tasksCreating a workspace
Participates in current executionYesNo

Conclusion:

  • runtime answers “what do we initialize from?”
  • workspace answers “what project are we actually running now?”
ComparisonWorkerSandbox
FocusExecution roleExecution host
Main question”Who executes?""Which environment hosts execution?”
Typical actionsConsume runs, drive the tool loop, flush / evictProvide files, processes, commands, mounts, lifecycle

Conclusion:

  • worker is the role
  • sandbox is the environment that hosts that role

File reads, writes, and command execution always target the active execution copy, not abstract workspace metadata.

So:

  • use /workspaces for catalog, metadata, create, delete, and lifecycle
  • use /sandboxes for file reads, file writes, and command execution

This keeps the API shape stable across:

  • embedded
  • self_hosted
  • e2b

Typical flow:

  1. a workspace is created or imported logically
  2. controller / owner routing decides which worker owns it
  3. the worker materializes an Active Workspace Copy in its host environment
  4. runs perform file operations, commands, and tool calls against that Active Workspace Copy
  5. on idle, drain, or delete, the workspace is flushed / evicted back to external storage or the managed source root
ModeWhere the active execution copy usually lives
embeddedA locally accessible workspace on the same machine
self_hostedAn Active Workspace Copy inside a remote sandbox
e2bAn Active Workspace Copy inside a remote E2B sandbox

Important:

  • the logical workspace identity stays the same
  • only the host location of the active execution copy changes

If you are reading:

  • terminology.md read it for naming boundaries
  • workspace/README.md read it for what a workspace declares
  • server-config.md read it for where these objects land in deployment
  • openapi/workspaces.md read it for project and capability management
  • openapi/files.md read it for file and command access on the active execution copy

Remember this order:

  1. Runtime initializes a Workspace
  2. Spec extends a Runtime
  3. Engine runs a Workspace
  4. Worker executes a Run inside a Sandbox
  5. an active Workspace materializes into an Active Workspace Copy