AIP-36: SANDBOX (sandbox/v1): compute environment policy block

A composable schema block defining the `sandbox` field — provider, config, command env, network egress, resource limits — for any manifest that names a compute environment for agent-issued shell commands. Sibling primitive to STORAGE.md (AIP-35); inline or ref, mirroring AIP-17 RUNNER and AIP-19 SECRETS.

FieldValue
AIP36
TitleSANDBOX (sandbox/v1): compute environment policy block
StatusReview
TypeSchema
Domainsandbox.sh
RequiresAIP-17 (RUNNER), AIP-19 (SECRETS), AIP-35 (STORAGE)

Abstract

This AIP defines the sandbox schema block — provider (which backend), config (provider-specific connection fields), limits (resource caps), env (variables injected at command invocation, resolved via SECRETS.md), network (egress allowlist) — and the defineSandbox(...) standard signature that consumes it.

sandbox describes a single concern: the compute environment hosting agent-issued shell commands (execute_command, get_process_output, kill_process, etc.). It is the sibling of STORAGE.md (AIP-35), which describes durable file storage. Together they compose a workspace's runtime (per AIP-34).

The block is composable: any manifest that names a compute environment MAY embed a sandbox block inline, or MAY reference a sibling SANDBOX.md file or registry slug.

This is a schema-block AIP, not a file format users always author standalone. There MAY be <slug>.SANDBOX.md files in a workspace when the policy is reusable; otherwise the block is inline in its parent manifest.

Motivation

Sandbox abstractions have appeared independently in multiple ecosystems:

  • Mastra ships a MastraSandbox interface implemented by LocalSandbox, @mastra/e2b, @mastra/modal, @mastra/daytona, @mastra/blaxel — composed alongside MastraFilesystem in the Workspace constructor.
  • The mcp-core registry pattern (referenced impl: a SandboxProviderAdapter interface with create / connect / isAlive / kill / getUrl / writeFile / readFile / runCommand) — used to host third-party MCP servers in cloud sandboxes.
  • Subprocess sandboxes with kernel-level isolation (Node --permission flags + bwrap) — used to run workspace- authored code with declarative grants.

Each of these is a real, working pattern. They diverge on lifecycle (workspace-lifetime vs per-MCP-connector vs per-invocation), but they share the same provider primitive: a thing you can run a command in, with bounded I/O, network, and resource allowances.

SANDBOX.md extracts the policy declaration into a portable block that any of these consumers can read. It's the contract layer; lifecycle stays per-consumer.

Three problems this fixes:

  1. Provider enums get incoherent if conflated with storage. Lumping s3, azure-blob, e2b, and modal into one provider enum mixes durable backends with ephemeral compute. Splitting clarifies — STORAGE.md is files, SANDBOX.md is commands.

  2. Lifecycle differs. A storage backend is durable; a sandbox is ephemeral, often with pause/resume semantics. They need different operational verbs.

  3. Policy axes differ. Storage policy is about read/write, exclude lists, sync mode. Sandbox policy is about resource caps, allowed network egress, env-var injection. A shared policy block can't model both cleanly.

SANDBOX.md extracts the compute-environment policy into a portable, reusable block that composes with — but is independent of — STORAGE.md.

Design principles

  1. Inline or ref, mirroring AIP-17 / AIP-19 / AIP-35. Most consumers inline the block. Reusable policies live in their own <slug>.SANDBOX.md and are referenced.

  2. Optional in WORKSPACE.md. A workspace MAY declare no sandbox at all (storage-only workspace). The host MUST tolerate the absence and refuse execute_command-class tools when no sandbox is configured.

  3. Provider names are the primary axis. The provider string is the first thing consumers branch on. The provider namespace is open: hosts MAY register additional provider ids.

  4. Config is a typed object per provider. Discriminated union keyed on provider. No Record<string, unknown> opt-out.

  5. Env never inline. Sandbox env vars MUST resolve through AIP-19 SECRETS.md auth.ref, not embedded plaintext. Static passthrough (NODE_ENV, DEBUG) is allowed via a separate passthrough list.

  6. Network is allow-list, not deny-list. network.egress declares which hosts the sandbox MAY reach. Empty/missing = no egress. Hosts MUST enforce.

  7. Limits are advisory but enforceable. Hosts SHOULD enforce timeout_ms / memory_mb / cpu_ms when the underlying sandbox primitive supports it. Hosts that can't enforce a cap SHOULD warn at registration.

Specification

The sandbox block

sandbox:
  provider: local | mastra-e2b | mastra-modal | mastra-daytona | mastra-blaxel
  config:
    # provider-specific shape — see "Provider config shapes" below
  limits:
    timeout_ms: 30000
    memory_mb: 1024
    cpu_ms: 30000
  env:
    auth:
      ref: ./SECRETS.md                # AIP-19 — credentials live there
      state: { env: ["OPENAI_API_KEY", "STRIPE_SECRET"] }
    passthrough: ["NODE_ENV", "DEBUG"] # static host vars to forward
    autoPassthrough: true              # opt-in: forward the resolved billing-credential var NAME
  join:
    tokenEnv: AGENTPROTO_JOIN          # host var holding a join-token URL, forwarded by the same name
  extraPorts: [3000, 5173]             # app ports to expose at boot
  network:
    egress: ["api.openai.com", "*.anthropic.com"]
  mounts:                              # AIP-36 mounts (see below) — optional
    - source: workspace                 # alias for "the parent workspace storage"
      at: /workspace
      mode: read-write
    - source: { ref: "@agentik/python-libs" }
      at: /vendor/python-libs
      mode: read-only
  identity:                            # AIP-23 identity-ref — optional
    ref: "bot://agentik"
  lifecycle:
    pause_after_idle: idle-600          # AIP-37 event name (or `idle-N` shorthand)
    destroy_on: workspace-close         # AIP-37 event name
  read_only: false                     # if true, no command execution permitted

Standalone SANDBOX.md frontmatter

When the block lives in its own file, the frontmatter adds an id and version for addressability:

---
schema: sandbox/v1
id: "@<owner-slug>/<sandbox-slug>"
version: 1.0.0
provider: <as above>
config: { ... }
limits: { ... }
env: { ... }
network: { ... }
lifecycle: { ... }
read_only: false
---

Embedding in a parent manifest (WORKSPACE.md example)

sandbox:
  inline:                              # exclusive with ref
    provider: mastra-e2b
    config: { template: "code-interpreter-v3" }
    limits: { timeout_ms: 60000, memory_mb: 2048 }
    network: { egress: ["api.openai.com"] }
  # OR
  # ref: ./sandbox/main.SANDBOX.md
  # OR
  # ref: "@acme-corp/shared-modal-policy"

Required fields

FieldTypeDescription
providerstringBackend kind. See enumerated set + extension rules below.
configobjectProvider-specific connection fields. Shape varies per provider.

Optional fields

FieldTypeDefaultDescription
limitsobject{ timeout_ms: 30000 }Resource caps per command.
envobject{}{ auth: { ref, state }, passthrough: [...], autoPassthrough?: boolean }. autoPassthrough is opt-in (default off): forward the spawn's resolved billing-credential env-var NAME (e.g. ANTHROPIC_API_KEY) into passthrough, so a fresh box inherits host auth without the caller naming vars. Only the name is injected — the value travels via the normal passthrough mechanism.
joinobject(none)Auto-join wiring: { tokenEnv: string } names a host env var whose value (a join-token URL) is forwarded into the sandbox under the SAME name at boot, so the box can auto-register with the daemon that minted the token. Equivalent to adding that name to env.passthrough, kept as a distinct field because its purpose differs from an arbitrary forwarded secret. A no-op when the named host var is not set — it MUST NOT fail the boot.
extraPortsinteger[][]App ports to expose at boot. Resolved into BootedSandbox.ports (port → public URL) by providers that support port exposure.
networkobject{ egress: [] }{ egress: string[] } — host allowlist. Empty = no egress.
mountsarray[]Filesystems mounted inside the sandbox. See "Mounts" section below.
identityobject | array(none)AIP-23 identity-ref block — owner of the sandbox processes. See AIP-23 identity-ref.
policyobject | array(none)AIP-38 POLICY block — access grants on sandbox actions (sandbox:execute, sandbox:network-egress, etc.). Inline / ref / file. See AIP-38 POLICY.md.
lifecycleobject{}{ pause_after_idle_ms?, destroy_on_workspace_close? }.
read_onlybooleanfalseReject command execution at the sandbox layer.
metadataobject{}Free-form, namespaced.

Standalone-only fields

FieldTypeDescription
schemastringAlways sandbox/v1.
idstring@<owner-slug>/<sandbox-slug>. Globally addressable when reused.
versionsemver stringSpec version of THIS file.

Provider enumerated set (Day 1)

providerImplementationLifecycleNotes
localMastra LocalSandbox (from @mastra/core/workspace)workspace-lifetimeDev / self-host. Default in createAgentWorkspace({ enableSandbox: true }).
mastra-e2b@mastra/e2bper-call, freshCloud isolation.
mastra-modal@mastra/modalpersistent w/ pause/resumeLong-lived sessions.
mastra-daytona@mastra/daytonapersistentDev-environments.
mastra-blaxel@mastra/blaxelper-callCloud isolation.
e2b@agentproto/sandbox-e2bpersistent w/ pause/resumeDirect E2B integration.
computer@agentproto/sandbox-computerpersistent w/ pause/resumeSelf-hosted microVM fleet behind a controller. Shared box per v1.2; egress pool per v1.3.
node-permissionNode --permission subprocess + optional bwrapper-invocationPer-tool grants for workspace-authored code.

Hosts MAY register additional providers (e.g. flyio-machines, cloudflare-containers, custom internal). The registry name MUST NOT collide with the enumerated set.

On the relationship to existing implementations. The mcp-core SandboxProviderAdapter (with create / connect / isAlive / kill / getUrl / writeFile / readFile / runCommand) is prior art that informed this AIP. Where Mastra's MastraSandbox is available for a given provider, conformant implementations SHOULD wrap it rather than reimplement. The AIP defines the declarative contract (what a workspace asks for); the runtime execution is the consumer's choice — Mastra sandboxes for the canonical path, custom adapters for cases Mastra doesn't yet cover.

Provider config shapes

Every provider's config also accepts installHarnesses (string[]): semantic harness slugs to pre-install in the box at boot (e.g. ["hermes", "claude-code"]). Each expands to @agentproto/harness-<slug>@latest plus that harness's declared boot extras; a config.installPackages pin for the same package always wins. Additive — absent means no extra install. The field was named installAdapters and the package prefix was adapter- in earlier drafts; both are removed from this AIP (AIP-70 §4), and the reference implementation keeps reading installAdapters until its next breaking release.

# local
config:
  cwd: string                    # working directory; defaults to workspace root
  shell: "/bin/bash" | "/bin/sh" # default: /bin/sh

# mastra-e2b
config:
  template: string               # e2b template id
  api_key_ref: string            # SECRETS.md slug for E2B API key
  region?: "us-east-1" | "eu-west-1"

# mastra-modal
config:
  app_name: string
  function_name: string
  api_token_ref: string

# mastra-daytona
config:
  workspace_id: string
  api_key_ref: string

# mastra-blaxel
config:
  workspace: string
  api_key_ref: string

# e2b
config:
  template: string               # e2b template id
  api_key_ref: string            # SECRETS.md ref for the provider API key

# computer
config:
  template: string               # microVM image / template id
  cpus: number                   # vCPUs per sandbox
  memoryMiB: number              # memory budget per sandbox
  rootDiskMiB: number            # root disk size
  ttlSeconds: number             # provider-side maximum lifetime
  maxSessions: number            # max sessions sharing one box (v1.2)
  egress: string[]               # host allowlist; same semantics as network.egress
  egressIp: string               # shared | auto | dedicated | <slot id> (v1.3)
  cliVersion: string             # agentproto CLI version installed in the box at boot

All credentials in these shapes are SECRETS.md refs, never inline values. For computer, config-level egress and egressIp map onto network.egress and network.egressIp; the network block is the portable form. Config-level cpus and memoryMiB map onto limits.cpus and limits.memoryMb.

defineSandbox standard signature

defineSandbox(definition: SandboxDefinition): SandboxHandle

interface SandboxDefinition {
  schema?:    "sandbox/v1"             // standalone files only
  id?:        string                    // standalone files only
  version?:   string                    // standalone files only

  provider:   string
  config:     Record<string, unknown>   // typed per provider; spec'd in this AIP

  limits?: {
    timeoutMs?:  number
    memoryMb?:   number
    cpuMs?:      number
    cpus?:       number   // vCPUs, may be fractional (v1.3)
  }
  env?: {
    auth?:            { ref?: string; state?: { env?: string[] } }
    passthrough?:     string[]
    autoPassthrough?: boolean
  }
  join?:       { tokenEnv: string }
  extraPorts?: number[]
  network?: {
    egress: string[]
    egressIp?: "shared" | "auto" | "dedicated" | string   // v1.3
  }
  lifecycle?: {
    pauseAfterIdleMs?:        number
    destroyOnWorkspaceClose?: boolean
  }
  readOnly?:  boolean
  metadata?:  Record<string, unknown>
}

Conformance rules

  1. Inline and ref are mutually exclusive. A consumer manifest embedding the block uses exactly one form per occurrence.

  2. Env credentials never inline. Implementations MUST reject sandbox blocks containing plaintext credentials. Use env.auth.ref → SECRETS.md per AIP-19.

  3. Network egress is allow-list. A sandbox with no network block MUST be granted no egress. Validators that silently allow all egress on missing config are non-conformant.

  4. read_only: true MUST be enforced. Command execution through a read-only sandbox handle MUST fail with a typed error (sandbox_read_only) before reaching the backend.

  5. No I/O at parse time. Parsing a SANDBOX.md or sandbox block MUST NOT trigger credential resolution, network calls, or backend instantiation. Materialization is lazy.

  6. Lifecycle features are advisory. A pause_after_idle_ms declaration on a provider that doesn't support pause/resume (e.g. local, mastra-e2b) MUST be ignored — not rejected.

Mounts (filesystems inside the sandbox)

The mounts block declares which filesystems are accessible from inside the sandbox at which paths. Maps directly to Mastra's Workspace.mounts field (since @mastra/[email protected]) — a sandbox provider that wraps a Mastra workspace passes the resolved mounts through.

sandbox:
  mounts:
    - source: workspace               # alias = the parent workspace's storage
      at: /workspace
      mode: read-write
    - source: { ref: "@agentik/python-libs" }   # AIP-34 workspace ref
      at: /vendor/python-libs
      mode: read-only
    - source: { inline: { provider: cloud-bucket, config: {...} } }  # ad-hoc
      at: /cache
      mode: read-write

Each entry:

FieldTypeDescription
sourcestring | objectWhat to mount. "workspace" = the parent workspace's primary storage. Otherwise an inline storage block (per AIP-35) or a ref to a workspace / storage.
atstringAbsolute path inside the sandbox where the mount appears. Hosts MUST normalise (no .., leading /).
mode"read-write" | "read-only"Default read-write. A read-only mount blocks writes at the sandbox layer.

Sandbox-relative semantics : the path at is inside the sandbox process, not the host. Sandboxed processes see the mounts as regular filesystem paths (e.g. cat /workspace/README.md). Host-side, the bytes route back through the storage provider that backs the mount.

Why mounts matter : without a mount, a sandbox like E2B/Modal has only its own ephemeral fs. Bytes written there die when the sandbox dies. Mounts let the sandbox read AND persist into durable workspace storage — closing the loop for github-backed workspaces where the agent commits code from inside the sandbox.

Composition with STORAGE.md

A workspace's runtime is the product of its storage and sandbox declarations:

# WORKSPACE.md
storage:
  inline:
    provider: github
    config: { owner: acme, repo: workspace, branch: main }
sandbox:
  inline:
    provider: mastra-e2b
    config: { template: "code-interpreter-v3" }
    network: { egress: ["api.openai.com"] }
    mounts:
      - source: workspace            # mount the github-backed storage
        at: /workspace                # inside the e2b sandbox
        mode: read-write

The host materializes both; agent-callable file tools route to the storage filesystem, agent-callable command tools route to the sandbox. Sandboxed commands write to /workspace → the storage provider routes those writes through its sync layer (commit + push per the storage's STORAGE.md.sync policy).

Reference resolution

A ref field accepts three forms (same as STORAGE.md):

  1. Workspace-relative path: ./sandbox/main.SANDBOX.md
  2. Cross-workspace path: ../shared/team.SANDBOX.md
  3. Registry slug: @<owner-slug>/<sandbox-slug>

Resolution failures MUST surface as a typed error (sandbox_ref_unresolvable).

Example — standalone SANDBOX.md

---
schema: sandbox/v1
id: "@acme-corp/shared-modal-policy"
version: 1.0.0
provider: mastra-modal
config:
  app_name: agentik-sandbox
  function_name: code_runner
  api_token_ref: org/acme/modal-token
limits:
  timeout_ms: 120000
  memory_mb: 4096
env:
  auth:
    ref: ./SECRETS.md
    state: { env: ["OPENAI_API_KEY", "STRIPE_SECRET"] }
  passthrough: ["NODE_ENV"]
network:
  egress: ["api.openai.com", "api.stripe.com"]
lifecycle:
  pause_after_idle_ms: 300000
  destroy_on_workspace_close: false
read_only: false
---

## Description

Shared Modal sandbox for Acme's analytics workspaces. Pauses after
5 minutes idle to control cost; reuses the org's Modal API token.

Security considerations

SANDBOX.md is declarative: a malicious manifest can claim any provider or config. Hosts MUST validate:

  • env.auth.ref resolves to a SECRETS.md the workspace's owner is authorised to reveal.
  • network.egress entries are on an allow-list of permitted destinations under workspace policy.
  • provider is registered in the host's provider registry; unknown providers MUST be rejected, never silently treated as a default.

Sandbox providers vary widely in their isolation guarantees. Hosts SHOULD document which providers are considered "trusted" under their policy framework. A local provider grants host-process access — granting it to an untrusted manifest is a sandbox escape by definition.

Open questions

  1. Multi-sandbox per workspace. Should a workspace declare multiple sandboxes (e.g. python + node separately)? Defer until concrete need.

  2. Sandbox-to-storage mount syntax. Resolved by the mounts block above (added 2026-05-03 per AIP-36 v1.1).

  3. Cost / quota declarations. Sandbox usage is metered by most cloud providers. Whether limits include a cost cap (max_cost_units_per_run) is open.

See also


Amendment v1.2 — shared box (2026-10-18)

Historically, a box was the sandbox of ONE session: the first session to finish destroyed it, right under the feet of the other sessions still attached to it. Amendment v1.2 makes the box a multi-tenant resource, with an explicit ATTACH / DETACH cycle and a declared teardown policy. The model remains GENERIC across providers (e2b, computer/msb, local…) — nothing below is specific to e2b.

1. Attachments — the shared box

A session attaches to a box already running (at boot, or via reuse/attach). It appears in the box's list of attached sessions. Execution inside the box stays isolated (§3): it is the lifecycle that is shared, not the files.

Rule
R1Attachments are durable (ledger on disk): the refcount is authoritative even across a daemon restart.
R2A session's teardown is by default a DETACH: stopping a session must never affect the box while other attachments remain.
R3Only the detach of the LAST session triggers the teardown policy (§2).

2. Teardown policy declared on the box (lifecycle.teardown)

The policy is declared ON the box (inside the sandbox.lifecycle block), not per session. Two cases:

sandbox:
  lifecycle:
    teardown:
      empty: destroy | pause | keep-<N>->destroy | keep   # case (a): zero attachments
      emptyIdleAfterMs: <X>                               # case (b): all idle
      destroyable: true
      idleYMs: <Y>                                        # picked up in §5
  • Case (a) — no attachments left. As soon as the refcount reaches zero, the rule applies:

    • destroy (default): immediate teardown;
    • pause: immediate provider-side pause (e2b bills a paused box — useful only on a provider with true pause/resume);
    • keep-<N>->destroy: arm an N ms delay before teardown (cancellable: a new attachment cancels it);
    • keep: never torn down on this criterion (another event can still destroy it: manual, provider TTL, destroy_on_workspace_close).
  • Case (b) — all attachments idle. If ALL attached sessions are idle for more than emptyIdleAfterMs AND the box is declared destroyable, the box is torn down (or paused). A single active session keeps it alive.

3. Per-session checkout isolation

Every attached session works on its OWN checkout, without leaving the box (the box is shared, not the working tree):

  • workspace/repo differs per session: one git clone per session, under /workspace/<session-id>/<repo>;
  • same repo, several sessions: one git worktree per session under /workspace/<session-id>/ — shared object storage, distinct HEAD / index / branch, zero commit collisions.

4. Named "pool" declaration in the workspace

So that an agent lands on a shared box by default, the workspace (AIP-34) can declare the box by label:

sandbox:
  ref: "<label>"   # attaches to the box labelled <label>

Resolution reuses the standard ref resolution: exact label, unique id prefix, or @owner/label slug. A box declared as a ref is attached, never cold-booted, so the refcount (§1) is identical whichever the arrival path.

5. Detach criteria — deterministic, then decision

Evaluation order: 1) the deterministic criteria; 2) if one exists, the decision (§6); 3) by default, determinism wins.

Deterministic criteria (default):

CriterionDetaches when
session-endthe session ends normally
session-killthe session is explicitly stopped
session-crashthe session crashes
idle-<Y>the session has been idle for more than Y ms — ONLY if the box declares idleYMs; no window, no criterion

Default: no decision declared → the deterministic order applies; the most recent criterion wins.

6. DECISION.md hook (optional — extension point)

A box MAY declare a decision (AIP-65 DECISION.md) via sandbox.lifecycle.decision.ref:

lifecycle:
  decision:
    ref: ./sandbox-teardown.DECISION.md

The decision answers the typed question "what should happen to this box?" with the options destroy / pause / keep. It is evaluated AFTER the deterministic order, at every detach AND before every immediate teardown, and may take precedence (e.g. "keep the box if a session has unpushed work"). A host without a decision engine treats this field as an extension point: the deterministic criteria remain in force, with at most a warning.

7. Emitted events

The host emits the following events (reserved names, no namespace):

EventFires when
sandbox:attacheda session joins the attachment list
sandbox:detacheda session leaves the attachment list
sandbox:destroy-scheduleda deferred destroy is armed (case (a) keep-<N> or case (b)) — cancelled by a new attachment
sandbox:destroyedthe box has been destroyed (or paused)

Amendment v1.3: egress address, host capacity, provider registry (2026-10-20)

Amendment v1.3 covers three operational concerns that show up once sandboxes run on a finite, shared fleet: which public source address outbound traffic uses, whether a host has room to admit the sandbox, and which providers a host may register. Like v1.2, everything below is GENERIC across providers. The reference implementation is the self-hosted microVM provider computer, but no rule below depends on it.

1. Egress address (network.egressIp)

network.egressIp is optional and selects the public source address that the sandbox's outbound traffic uses.

sandbox:
  network:
    egress: ["api.openai.com"]
    egressIp: shared        # shared | auto | dedicated | <slot id>
ValueMeaning
shared (default)The host's default address, shared with other sandboxes on that host.
autoOne address from the host's pool, least used. It MAY still be shared with other sandboxes.
dedicatedAn address from the pool used by no other sandbox for this sandbox's whole life. Refused if none is free.
<slot id>A specific pool slot (string matching /^[a-z0-9]{1,8}$/). The sandbox is placed on that slot; the slot MAY be shared with other non-dedicated sandboxes.

Rules:

  • The address is fixed for the sandbox's life. It is kept across pause/resume and host restart, and freed when the sandbox is destroyed (deleted).
  • A fork does not inherit it. A fork starts from the default (shared) unless it declares its own value.
  • A provider with no address pool MUST refuse any value other than shared with a typed error (sandbox_egress_pool_unavailable). It MUST NOT silently fall back to shared.
  • dedicated with no free address fails with sandbox_egress_pool_exhausted.
  • A slot already held by a dedicated sandbox fails with sandbox_egress_slot_dedicated.
  • auto never picks a slot held by a dedicated sandbox. When every slot is dedicated, auto fails with sandbox_egress_pool_exhausted.
  • Only dedicated grants exclusivity. A requested slot id MAY be shared with other non-dedicated sandboxes.

Rationale: tenant isolation, attribution of outbound calls to a specific sandbox, and keeping one sandbox's reputation (for example an address that has been rate-limited or blocked) from affecting other sandboxes.

Non-normative: egressIp is for isolation and attribution. It MUST NOT be used to evade third-party rate limits or terms of service.

2. Assigned address on the booted sandbox

A provider that assigns an address reports it on the booted sandbox:

interface BootedSandbox {
  // ...
  egressIp?: { id: string; publicIp: string } | null
}

id is the pool slot id when one is assigned. publicIp is the public source address that outbound traffic uses. The field is absent or null when the provider does not track an address (for example a provider whose only mode is the host default).

3. Host capacity

Providers that place sandboxes on finite hosts SHOULD admit a sandbox only if its declared memory and cpus fit the host's remaining budget. If they do not fit, the provider MUST refuse before any resource is created, with a typed error:

{
  code: "sandbox_capacity"
  resource: "memory" | "cpus"
  requested: number
  available: number
  retryAfterMs: number
}

retryAfterMs is the provider's estimate of when capacity may free up. Consumers SHOULD retry with backoff or pick another host.

limits in SandboxDefinition gains cpus alongside memoryMb:

limits?: {
  timeoutMs?: number
  memoryMb?:  number
  cpuMs?:     number
  cpus?:      number   // vCPUs, may be fractional
}

Provider config-level cpus and memoryMiB fields map onto limits.cpus and limits.memoryMb. When both are present, the declared limit is what the admission check uses.

4. Provider registry

The following rows are added to the provider set in §Provider enumerated set; the existing mastra rows remain.

providerImplementationLifecycleNotes
e2b@agentproto/sandbox-e2bpersistent w/ pause/resumeDirect E2B integration.
computer@agentproto/sandbox-computerpersistent w/ pause/resumeSelf-hosted microVM fleet behind a controller. Shared box per v1.2; egress pool per v1.3.

Their config shapes live in §Provider config shapes next to the mastra ones. For computer:

config:
  template: string               # microVM image / template id
  cpus: number                   # vCPUs per sandbox
  memoryMiB: number              # memory budget per sandbox
  rootDiskMiB: number            # root disk size
  ttlSeconds: number             # provider-side maximum lifetime
  maxSessions: number            # max sessions sharing one box (v1.2)
  egress: string[]               # host allowlist; same semantics as network.egress
  egressIp: string               # shared | auto | dedicated | <slot id> (v1.3)
  cliVersion: string             # agentproto CLI version installed in the box at boot

Credentials are SECRETS.md refs only, never inline values.


Amendment v1.4: placement ladder, preflight probes, egress health (2026-11-03)

Amendment v1.3 lets a spawn pick one sandbox and one egress address. Once a fleet is finite and some models are capped per source address, one choice is not enough: the box may not fit, its address may already be capped for the model, or the model may not answer from it at all. Amendment v1.4 specifies what the reference runtime already ships for that case: an ordered placement ladder of sandboxes tried before the agent starts, preflight probes that test a booted box before the agent runs on it, and an egress health ledger that remembers which addresses are cooling down for which model.

Every normative statement below cites the reference implementation it mirrors, as path:line in agentproto/ts at commit 0380c2b (main after PR #2488). Paths are under packages/ unless they start with .github/. The JSON Schema of the spawn input is resources/aip-36/draft/PLACEMENT.schema.json.

1. Placement ladder (placement)

A session spawn (AIP-46 SpawnAgentRequest; in the reference implementation the agent_start tool and its HTTP twin POST /sessions/agent) MAY carry placement:

interface PlacementInput {
  ladder: PlacementRung[]          // 1 to 8 rungs, tried in order
}

interface PlacementRung {
  sandbox: string | SandboxSpec    // provider slug or AIP-36 inline spec
  model?: string
  access?: { profileRef?: string; profileRefs?: string[] }
  preflight?: string[]             // probe ids, §2
  turnRetry?: TurnRetryInput | null // mid-run policy, §4
}

Source: runtime/src/placement-ladder.ts:17-40, runtime/src/agent-start-schema.ts:535-539, runtime/src/http-server.ts:6408-6415.

Validation.

  • ladder MUST hold between 1 and 8 rungs, and a rung or the placement object with an unknown key MUST be refused with placement_invalid (runtime/src/placement-ladder.ts:17, :26-40; runtime/src/http-server.ts:7233-7241).
  • placement and a top-level sandbox are mutually exclusive. A spawn carrying both MUST be refused with placement_invalid, before any box is booted (runtime/src/session-spawn.ts:2487-2492, runtime/src/http-server.ts:7242-7247).
  • A rung boots a fresh box. A rung whose inline spec sets reuse MUST be refused with placement_invalid (runtime/src/placement-ladder.ts:114-120, runtime/src/session-spawn.ts:2504-2507).

Inheritance. A rung that omits model, access, preflight or turnRetry inherits the spawn's own top-level value for that axis. A value the rung sets replaces the top-level one; the two are never merged. The host MUST resolve the ladder this way before walking it, so each resolved rung is self-contained (runtime/src/placement-ladder.ts:122-136, runtime/src/session-spawn.ts:2497-2503). Every other spawn field (harness, cwd, modelPolicy, ...) is shared by all rungs (runtime/src/session-spawn.ts:2511).

The walk. The host tries rung 1 as an ordinary single-sandbox spawn with the rung's axes applied, then rung 2, and so on (runtime/src/session-spawn.ts:2508-2521):

  1. If the rung returns a session, the walk stops. No later rung is tried and nothing moves the session afterwards: a failure after the agent started is turnRetry's concern (§4), never the ladder's (runtime/src/placement-ladder.ts:1-6, :170-195).
  2. If the rung fails with one of the advance codes below, the host records the attempt and tries the next rung (runtime/src/placement-ladder.ts:67-92, :197-210).
  3. If the rung fails with any other code (bad cwd, unknown probe id, policy refusal, ...), the walk stops and the spawn fails with that code and message, plus the attempts so far in details.attempts (runtime/src/placement-ladder.ts:210, runtime/src/session-spawn.ts:2533-2538). Such a failure would repeat on every rung, or is a decision to stop.
  4. If every rung failed with an advance code, the spawn fails with sandbox_placement_exhausted and details.attempts (runtime/src/placement-ladder.ts:211-217, runtime/src/session-spawn.ts:2522-2531).

Advance codes (runtime/src/placement-ladder.ts:71-82). All of them are raised before the agent started:

CodeRaised when
sandbox_preflight_faileda preflight probe said ko (§2)
sandbox_boot_failedthe provider's boot threw, including a typed refusal such as sandbox_capacity (v1.3 §3) or sandbox_egress_pool_exhausted (v1.3 §1), carried as details.errorClass
sandbox_provider_not_foundthe rung's provider is not set up on this host
sandbox_proxy_failed, sandbox_workspace_setup_failed, sandbox_app_serve_failedthe box booted but the session's plumbing on it failed
sandbox_overflow_refused, sandbox_egress_pool_exhaustedthe provider refused the placement with that typed code
sandbox_egress_all_coolingevery egress address is cooling down for the model (§3); nothing was booted
device_offlinethe rung targets a device that is not connected

The criterion MUST be a typed code, never a match on a provider's message (runtime/src/placement-ladder.ts:8-10). When the provider throws an error carrying a sandbox_* code, the host reports sandbox_boot_failed with that code as details.errorClass, and the attempt records the more specific class (runtime/src/session-spawn.ts:7746-7756, runtime/src/placement-ladder.ts:94-108).

Record. Once the walk succeeds, the session record gains placement (runtime/src/sessions.ts:3148, runtime/src/session-spawn.ts:2542-2543):

interface SessionPlacement {
  rung: number                 // 0-based index of the rung in use
  ladder: PlacementRung[]      // the resolved ladder, so a restart can re-place
  attempts: PlacementAttempt[]
}

interface PlacementAttempt {
  rung: number                 // 0-based
  provider: string
  model?: string
  outcome: "ok" | "failed"
  errorClass?: string          // failure code, or its more specific details.errorClass
  egressIp?: string            // the box's public address, when the failure reported one
  durationMs: number
}

Source: runtime/src/placement-ladder.ts:45-65, :184-208. When at least one rung was skipped, the spawn result SHOULD carry a warning naming the rung in use and the skipped attempts (runtime/src/session-spawn.ts:2544-2556).

Restart. A restart that must boot a fresh box for a session whose record carries placement walks the recorded ladder again, under the same advance rules (runtime/src/session-restart-core.ts:2386-2412).

2. Preflight probes (preflight)

A preflight probe is a cheap check run against a freshly booted box before the agent starts, so that a placement that cannot work fails in seconds with a typed code instead of mid-run (runtime/src/sandbox-preflight.ts:1-29). A spawn names probes by id, either at top level with a sandbox or on a ladder rung (runtime/src/agent-start-schema.ts:530-534).

Verdicts. A probe answers one of (runtime/src/sandbox-preflight.ts:12-20, :34-44):

VerdictMeaning
okthe box passes this check
kothe box demonstrably cannot do it; carries the same failure class a live turn would (usage-limit, rate-limit, ...)
unknownthe probe could not decide (timeout, missing binary, unclassified failure)

unknown MUST NOT be treated as ko: a probe that cannot run never vetoes a placement (runtime/src/sandbox-preflight.ts:18-20). A probe that throws or exceeds its budget is unknown, and every command it runs in the box is clamped to that budget (runtime/src/sandbox-preflight.ts:188-223).

Running. Probes run in the order given, duplicates removed, stopping at the first ko (runtime/src/sandbox-preflight.ts:240-257).

  • An id that no probe is registered under MUST fail the spawn with sandbox_preflight_invalid before the box is booted (runtime/src/session-spawn.ts:7394-7405). It is not an advance code, so it ends a ladder walk.
  • When the provider cannot run commands in the box, or the spawn carries an explicit credential the probe cannot present, the probes are skipped with a warning; they do not fail the spawn (runtime/src/session-spawn.ts:7821-7833).
  • On ko, the host MUST release the box (detach when other sessions share it, otherwise stop a fresh box or pause a reused one) and fail the spawn with sandbox_preflight_failed (runtime/src/session-spawn.ts:7863-7880), whose details carry probe, errorClass, probeDetail, egressIp, provider, sandboxId and the full outcomes list (runtime/src/sandbox-preflight.ts:259-293). Probe output MUST be scrubbed of credential-shaped text before it leaves the host (runtime/src/sandbox-preflight.ts:103-118).

The model-answers probe. The one built-in probe (runtime/src/sandbox-preflight.ts:93-99, :120-178):

  • It sends the one-line prompt reply ok to the session's model through the session's own harness, from inside the box, so the answer travels from the box's egress address.
  • It knows a one-line command for the opencode harness only. Any other harness yields unknown (runtime/src/sandbox-preflight.ts:120-128, :141-144).
  • A model id outside ^[A-Za-z0-9][A-Za-z0-9._:@/+-]*$ is not probed (unknown): the id reaches a shell command line (runtime/src/sandbox-preflight.ts:98-99, :145-147).
  • ko requires a classified failure. A non-zero exit or an empty answer is held to the full classification; a zero-exit answer is ko only for a usage cap, since a harness can print the provider's refusal and still exit 0 (runtime/src/sandbox-preflight.ts:153-163).
  • Default budget: 90 s (runtime/src/sandbox-preflight.ts:94-95).

3. Egress health and cooling

This section extends v1.3 §1 (network.egressIp). Some providers cap a model per source address, so "model M is capped" really means "model M is capped from this address". A host MAY keep an egress health ledger of such observations. The reference implementation does (runtime/src/egress-health.ts:1-15).

Entries. One entry per (publicIp, model, errorClass) with an expiry (runtime/src/egress-health.ts:39-51):

errorClassDefault cooldown
usage-limit60 min
rate-limit10 min

A cooldown is clamped to at most 6 h, and recording a cooldown MUST NOT shorten an active one for the same key (runtime/src/egress-health.ts:22-34, :147-168). Ledger writes are best-effort: a ledger failure MUST NOT fail a spawn or a turn (runtime/src/egress-health.ts:11-14, :111-120).

Writers. A cooldown is recorded when:

  1. a preflight ko with class usage-limit or rate-limit happens on a box that reports a public address, for a spawn that names a model (runtime/src/session-spawn.ts:7849-7862);
  2. a live turn of a sandboxed session ends in an error classified usage-limit or rate-limit, whatever the session's own turnRetry policy opted into; a retry-after hint on a rate limit sets the duration (runtime/src/turn-retry.ts:1296-1314);
  3. an operator-requested probe of the pool says ko (below).

An ok from that probe clears every cooldown on the address for the model (runtime/src/egress-health-report.ts:123-189).

Readers: egressIp: "auto". v1.3 §1 defines auto as "one address from the host's pool, least used". When the spawn names a model, the host MAY pass the provider a read view of the ledger for that model (runtime/src/session-spawn.ts:7653-7655). A provider given that view:

  • MUST NOT place the box on a slot whose address is cooling down for the model; it names a healthy slot explicitly, least loaded first, ties by slot id (sandbox-computer/src/provider.ts:1082-1140), and moves to the next healthy slot when the controller refuses one as dedicated or full (sandbox-computer/src/provider.ts:1251-1263);
  • MUST fail with sandbox_egress_all_cooling, without creating a box, when every slot of a readable pool is cooling. The error carries the model and, for each slot, slot, publicIp, until and errorClass (sandbox/src/agent-session-host.ts:338-375, runtime/src/session-spawn.ts:7657-7667);
  • falls back to the controller's own auto when the pool cannot be read (sandbox-computer/src/provider.ts:1129-1133).

sandbox_egress_all_cooling is an advance code (§1), so a ladder moves to its next rung without paying for a box.

Read and re-probe. A host that keeps the ledger SHOULD expose it read-only. The reference implementation's sandbox_egress_health tool lists the provider's pool slots, their public addresses and the active cooldowns, and boots nothing (runtime/src/egress-health-report.ts:85-107, :210-233). A re-probe boots one box per slot, one at a time, runs model-answers from it, and sets or clears the cooldown from the verdict; unknown and boot errors change nothing. There is no scheduler: a re-probe boots real boxes, so it runs only when asked (runtime/src/egress-health-report.ts:1-8, :123-189).

4. Ladder versus turnRetry

The two mechanisms split on one line: whether the agent has started.

Placement ladder (§1)turnRetry
Whenbefore the agent startsafter a turn failed on a live session
Movesto another sandbox (and the rung's model, access)same session: retry, rotate the model, apply a fallback overlay, or migrate to a fresh box
Triggertyped boot / preflight codes (§1)turn failure classes rate-limit, upstream-5xx, no-output-stall, usage-limit

Source: runtime/src/placement-ladder.ts:1-6, runtime/src/turn-retry-policy.ts:22-30, :83-95.

A rung's turnRetry is the policy of a session placed on that rung, so a session started on a metered rung can carry a different mid-run policy from one started on a free rung (runtime/src/placement-ladder.ts:146-155). Its fallback entries are config overlays (model, access.profileRef, harness), the reference implementation's subset of the AIP-46 ConfigOverlay (runtime/src/turn-retry-policy.ts:90-95, :214-227). They are walked by AIP-46 §Fallback rules on the session that the ladder placed; the ladder itself is never re-walked by a turn failure.

5. Metered rungs

A metered model is one that bills per use (in the reference CI lane, any id that does not end in -free and is not big-pickle, .github/agentproto-workflows/lib/sandbox-agent.mjs:208-209; the test is host policy, not part of this AIP).

  • A rung whose model is metered, and a rung or top-level turnRetry.fallback overlay whose model is metered, MUST be admitted only when an owner-controlled allowlist names that exact model id. The allowlist MUST be set by the owner of the account that pays (for example a repository variable a pull request cannot set), never by the caller that supplies the ladder alone.
  • An unlisted metered rung or overlay MUST be dropped before the spawn, fail closed. It MUST NOT be spawned and then refused.
  • A ladder left with no rung after that filtering MUST fail loudly; it MUST NOT degrade to a host spawn.

Source: .github/agentproto-workflows/lib/sandbox-agent.mjs:193-233 (allowlist AGENT_ALLOWED_METERED_MODELS, exact match), :274-281 (fallback overlays), :333-353 (rungs, empty ladder throws).

This is the placement form of AIP-68 §4.2, which never suggests a paid fallback for a free-only model when relaunching a session. In the reference implementation the gate sits where the ladder is built (the CI lane), not in the daemon: the daemon does not classify a model as metered. A host that accepts ladders from callers it does not trust MUST apply the gate itself, for example through the spawn's AIP-38 model policy (modelPolicy in the reference implementation). Note that a model-policy refusal (model_policy_refused, runtime/src/session-spawn.ts:4646-4659) is not an advance code, so it stops the walk instead of skipping the rung.

6. Workflow agent steps

An AIP-15 agent step MAY carry placement, with the same shape, as an alternative to its sandbox field. The two are mutually exclusive, and a host without placement support MUST fail the spawn loudly (workflow-runtime/src/types.ts:366-376, :457-462). The daemon host forwards it to the same spawn path as agent_start.placement (runtime/src/sessions-registry-agent-host.ts:306-339) and refuses it, like sandbox, inside an app boundary (runtime/src/sessions-registry-agent-host.ts:273-276).

7. Worked example (non-normative): the agentic review lane

The reference repository's PR review lane places its reviewer with this ladder (.github/agentic-review.json:114-189, trimmed):

{
  "reviewerModel": "opencode/deepseek-v4.1-flash-free",
  "reviewerPlacement": {
    "ladder": [
      { "sandbox": { "provider": "computer",
                     "config": { "template": "agentproto-workstation", "egressIp": "auto" } },
        "preflight": ["model-answers"] },
      { "sandbox": { "provider": "e2b" },
        "preflight": ["model-answers"] },
      { "sandbox": { "provider": "computer",
                     "config": { "template": "agentproto-workstation", "egressIp": "auto" } },
        "model": "opencode-go/deepseek-v4.1-flash" }
    ]
  }
}
  1. Rung 1: the self-hosted fleet with the free model, on a pool address not cooling for that model (§3), checked with model-answers (§2).
  2. Rung 2: e2b with the same free model, same probe.
  3. Rung 3: the fleet again with the metered opencode-go/deepseek-v4.1-flash, kept only when the owner's allowlist names it (§5). It carries no probe.

Mid-run, the lane's reviewerTurnRetry rotates among free models on rate limits, 5xx and stalls, and applies the metered model as a fallback overlay on a usage cap, under the same allowlist (.github/agentic-review.json:194-223, .github/agentproto-workflows/lib/sandbox-agent.mjs:308-315). A runner without the fleet's controller URL drops the computer rungs and runs on e2b (.github/agentproto-workflows/lib/sandbox-agent.mjs:341-344). The review step hands the ladder to the spawn through the AIP-15 placement field (.github/agentproto-workflows/pr-review/entry.mjs:33-36, :310-317).

8. Error codes

CodeEnds the walkSection
placement_invalidyes, before any boot§1
sandbox_placement_exhausted(result of an exhausted walk)§1
sandbox_preflight_invalidyes§2
sandbox_preflight_failedno, advances§2
sandbox_egress_all_coolingno, advances§3

9. Open questions (v1.4)

  1. Probe coverage. model-answers only knows the opencode harness. Other harnesses answer unknown, so their rungs are never skipped by a probe.
  2. egressIp and third-party limits. v1.3 §1 says egressIp MUST NOT be used to evade third-party rate limits. Skipping an address that is cooling for a model is close to that line. The ledger only records what a provider already answered, and the lane in §7 falls back to a paid model rather than cycling addresses, but where the line sits is not yet written down.
  3. A daemon-side metered gate. §5 is enforced where the ladder is built. Whether the daemon itself should know which models are metered (for example through the AIP-43 model registry) is open.

Resources

Supporting artifacts for AIP-36. Links open the file on GitHub — markdown and JSON render natively in GitHub's viewer. Browse the full resource tree →