Skip to main content

sandbox/

Sandbox files choose the agent computer for isolated file and shell work. Add one when the agent needs shell or file work outside the trusted app process.

Minimal Example​

// sandbox/default.ts
import { defineSandbox } from "@assemblyline-agents/core";

export default defineSandbox({
  adapter: "docker",
  image: "node:22",
  workingDirectory: "/workspace",
  env: ["OPENAI_API_KEY"]
});

Full Options​

FieldType / valuesDefaultEffect
adapterstring (required)—Sandbox backend kind: local, docker, daytona, e2b, modal, or a plugin kind.
imagestringadapter defaultContainer/base image for containerized adapters.
workingDirectory"/workspace""/workspace"Compatibility field for the canonical Assembly Line workspace. Other values are rejected.
envstring[]—Names of env vars forwarded into the sandbox.
snapshot{ mode, retainLast?, reason? }mode: "never"Infrastructure checkpoint policy (see Snapshots).
metadataJSON object—Structured app-specific metadata.

Multiple Sandbox Files​

Every .ts/.js file in sandbox/ compiles into the manifest's sandbox list (sorted by filename; the file stem becomes the entry name, and the entry's adapter falls back to the helper kind or the file stem when not declared). At runtime the host selects the entry whose adapter matches the gateway's sandbox adapter kind, and otherwise falls back to the first entry. So the filename itself does not select a sandbox — declare one file per adapter kind you configure, and let gateway.ts choose between them.

Filesystem Contract​

Assembly Line's hosted sandbox contract is a real, physical /workspace directory:

  • the default shell cwd is /workspace;
  • absolute shell paths such as /workspace/report.txt address that directory;
  • provider file APIs and shell commands address the same files; and
  • create, connect, and wake validate the contract before returning a session.

The contract is versioned in provider metadata and runtime session manifests. Assembly Line does not reconnect a sandbox created under an older or missing contract, and provider names include the contract version to avoid collisions. workingDirectory may be omitted or set to /workspace; a different path is rejected because a file-API alias cannot rewrite absolute paths inside shell commands. /runtime remains retired and rejected.

PathMutabilityPurpose
/memorywritable by policyDurable memory documents.
/skillswritable when self-improvement allows itDurable skill files.
/historyread-onlyBounded conversation history projection.
/filesread-onlyInput files and attachment projections.
/workspacewritableGenerated artifacts, scripts, and modified copies.

Core file tools accept these absolute paths, and hosted bash commands may use the same absolute paths directly.

Sandboxes are acquired lazily when a sandbox-backed tool or capability asks for one. Channel lifecycle events and final delivery do not require sandbox hydration.

Adapter Choices​

  • local: trusted development and tests only. It maps the logical paths onto a host temporary directory, so it cannot provide a physical host /workspace. Use Docker locally when exact shell namespace parity matters.
  • docker: local isolation baseline.
  • daytona, e2b: hosted sandbox choices.
  • modal: supported hosted Modal sandbox.

Use Docker or hosted sandboxes when untrusted or model-generated code needs an isolation boundary.

Snapshots​

Snapshots are infrastructure checkpoints, not normal turn persistence. Runtime state, memory, tool traces, delivery, and /workspace artifacts persist through Assembly Line state and blob sync.

export default defineSandbox({
  adapter: "daytona",
  image: "node:22",
  snapshot: {
    mode: "manual",
    retainLast: 3,
    reason: "operator-requested checkpoint"
  }
});

Supported modes are never, manual, on_failure, and always. The default is never.

Conventions​

  • Keep the local sandbox for trusted development and tests.
  • Run Docker for local conformance testing of absolute /workspace shell paths.
  • Write generated artifacts and modified input copies under /workspace.
  • Forward only the env vars the sandboxed work actually needs.