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.
| Field | Value |
|---|---|
| AIP | 36 |
| Title | SANDBOX (sandbox/v1): compute environment policy block |
| Status | Review |
| Type | Schema |
| Domain | sandbox.sh |
| Requires | AIP-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
MastraSandboxinterface implemented byLocalSandbox,@mastra/e2b,@mastra/modal,@mastra/daytona,@mastra/blaxel— composed alongsideMastraFilesystemin theWorkspaceconstructor. - The mcp-core registry pattern (referenced impl: a
SandboxProviderAdapterinterface withcreate / connect / isAlive / kill / getUrl / writeFile / readFile / runCommand) — used to host third-party MCP servers in cloud sandboxes. - Subprocess sandboxes with kernel-level isolation (Node
--permissionflags +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:
-
Provider enums get incoherent if conflated with storage. Lumping
s3,azure-blob,e2b, andmodalinto oneproviderenum mixes durable backends with ephemeral compute. Splitting clarifies — STORAGE.md is files, SANDBOX.md is commands. -
Lifecycle differs. A storage backend is durable; a sandbox is ephemeral, often with pause/resume semantics. They need different operational verbs.
-
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
-
Inline or ref, mirroring AIP-17 / AIP-19 / AIP-35. Most consumers inline the block. Reusable policies live in their own
<slug>.SANDBOX.mdand are referenced. -
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. -
Provider names are the primary axis. The
providerstring is the first thing consumers branch on. The provider namespace is open: hosts MAY register additional provider ids. -
Config is a typed object per provider. Discriminated union keyed on
provider. NoRecord<string, unknown>opt-out. -
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 separatepassthroughlist. -
Network is allow-list, not deny-list.
network.egressdeclares which hosts the sandbox MAY reach. Empty/missing = no egress. Hosts MUST enforce. -
Limits are advisory but enforceable. Hosts SHOULD enforce
timeout_ms/memory_mb/cpu_mswhen 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 permittedStandalone 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
| Field | Type | Description |
|---|---|---|
provider | string | Backend kind. See enumerated set + extension rules below. |
config | object | Provider-specific connection fields. Shape varies per provider. |
Optional fields
| Field | Type | Default | Description |
|---|---|---|---|
limits | object | { timeout_ms: 30000 } | Resource caps per command. |
env | object | {} | { 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. |
join | object | (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. |
extraPorts | integer[] | [] | App ports to expose at boot. Resolved into BootedSandbox.ports (port → public URL) by providers that support port exposure. |
network | object | { egress: [] } | { egress: string[] } — host allowlist. Empty = no egress. |
mounts | array | [] | Filesystems mounted inside the sandbox. See "Mounts" section below. |
identity | object | array | (none) | AIP-23 identity-ref block — owner of the sandbox processes. See AIP-23 identity-ref. |
policy | object | 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. |
lifecycle | object | {} | { pause_after_idle_ms?, destroy_on_workspace_close? }. |
read_only | boolean | false | Reject command execution at the sandbox layer. |
metadata | object | {} | Free-form, namespaced. |
Standalone-only fields
| Field | Type | Description |
|---|---|---|
schema | string | Always sandbox/v1. |
id | string | @<owner-slug>/<sandbox-slug>. Globally addressable when reused. |
version | semver string | Spec version of THIS file. |
Provider enumerated set (Day 1)
provider | Implementation | Lifecycle | Notes |
|---|---|---|---|
local | Mastra LocalSandbox (from @mastra/core/workspace) | workspace-lifetime | Dev / self-host. Default in createAgentWorkspace({ enableSandbox: true }). |
mastra-e2b | @mastra/e2b | per-call, fresh | Cloud isolation. |
mastra-modal | @mastra/modal | persistent w/ pause/resume | Long-lived sessions. |
mastra-daytona | @mastra/daytona | persistent | Dev-environments. |
mastra-blaxel | @mastra/blaxel | per-call | Cloud isolation. |
e2b | @agentproto/sandbox-e2b | persistent w/ pause/resume | Direct E2B integration. |
computer | @agentproto/sandbox-computer | persistent w/ pause/resume | Self-hosted microVM fleet behind a controller. Shared box per v1.2; egress pool per v1.3. |
node-permission | Node --permission subprocess + optional bwrap | per-invocation | Per-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 bootAll 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
-
Inline and ref are mutually exclusive. A consumer manifest embedding the block uses exactly one form per occurrence.
-
Env credentials never inline. Implementations MUST reject sandbox blocks containing plaintext credentials. Use
env.auth.ref→ SECRETS.md per AIP-19. -
Network egress is allow-list. A sandbox with no
networkblock MUST be granted no egress. Validators that silently allow all egress on missing config are non-conformant. -
read_only: trueMUST be enforced. Command execution through a read-only sandbox handle MUST fail with a typed error (sandbox_read_only) before reaching the backend. -
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.
-
Lifecycle features are advisory. A
pause_after_idle_msdeclaration 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-writeEach entry:
| Field | Type | Description |
|---|---|---|
source | string | object | What to mount. "workspace" = the parent workspace's primary storage. Otherwise an inline storage block (per AIP-35) or a ref to a workspace / storage. |
at | string | Absolute 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-writeThe 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):
- Workspace-relative path:
./sandbox/main.SANDBOX.md - Cross-workspace path:
../shared/team.SANDBOX.md - 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.refresolves to a SECRETS.md the workspace's owner is authorised to reveal.network.egressentries are on an allow-list of permitted destinations under workspace policy.provideris 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
-
Multi-sandbox per workspace. Should a workspace declare multiple sandboxes (e.g.
python+nodeseparately)? Defer until concrete need. -
Sandbox-to-storage mount syntax.Resolved by themountsblock above (added 2026-05-03 per AIP-36 v1.1). -
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
- AIP-17 — RUNNER.md — same composition pattern
- AIP-19 — SECRETS.md — referenced from
env.auth.ref - AIP-23 — IDENTITY.md — referenced from
identity? - AIP-26 — CODE.md — same composition pattern (inline / ref)
- AIP-34 — WORKSPACE.md — the primary consumer
- AIP-35 — STORAGE.md — sibling primitive (filesystem)
- AIP-37 — LIFECYCLE.md — event vocabulary referenced by
lifecycle.{pause_after_idle, destroy_on}
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 | |
|---|---|
| R1 | Attachments are durable (ledger on disk): the refcount is authoritative even across a daemon restart. |
| R2 | A session's teardown is by default a DETACH: stopping a session must never affect the box while other attachments remain. |
| R3 | Only 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
emptyIdleAfterMsAND the box is declareddestroyable, 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 cloneper session, under/workspace/<session-id>/<repo>; - same repo, several sessions: one
git worktreeper 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):
| Criterion | Detaches when |
|---|---|
session-end | the session ends normally |
session-kill | the session is explicitly stopped |
session-crash | the 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.mdThe 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):
| Event | Fires when |
|---|---|
sandbox:attached | a session joins the attachment list |
sandbox:detached | a session leaves the attachment list |
sandbox:destroy-scheduled | a deferred destroy is armed (case (a) keep-<N> or case (b)) — cancelled by a new attachment |
sandbox:destroyed | the 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>| Value | Meaning |
|---|---|
shared (default) | The host's default address, shared with other sandboxes on that host. |
auto | One address from the host's pool, least used. It MAY still be shared with other sandboxes. |
dedicated | An 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
sharedwith a typed error (sandbox_egress_pool_unavailable). It MUST NOT silently fall back toshared. dedicatedwith no free address fails withsandbox_egress_pool_exhausted.- A slot already held by a dedicated sandbox fails with
sandbox_egress_slot_dedicated. autonever picks a slot held by a dedicated sandbox. When every slot is dedicated,autofails withsandbox_egress_pool_exhausted.- Only
dedicatedgrants 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.
provider | Implementation | Lifecycle | Notes |
|---|---|---|---|
e2b | @agentproto/sandbox-e2b | persistent w/ pause/resume | Direct E2B integration. |
computer | @agentproto/sandbox-computer | persistent w/ pause/resume | Self-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 bootCredentials 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.
ladderMUST hold between 1 and 8 rungs, and a rung or theplacementobject with an unknown key MUST be refused withplacement_invalid(runtime/src/placement-ladder.ts:17,:26-40;runtime/src/http-server.ts:7233-7241).placementand a top-levelsandboxare mutually exclusive. A spawn carrying both MUST be refused withplacement_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
reuseMUST be refused withplacement_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):
- 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). - 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). - 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. - If every rung failed with an advance code, the spawn fails with
sandbox_placement_exhaustedanddetails.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:
| Code | Raised when |
|---|---|
sandbox_preflight_failed | a preflight probe said ko (§2) |
sandbox_boot_failed | the 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_found | the rung's provider is not set up on this host |
sandbox_proxy_failed, sandbox_workspace_setup_failed, sandbox_app_serve_failed | the box booted but the session's plumbing on it failed |
sandbox_overflow_refused, sandbox_egress_pool_exhausted | the provider refused the placement with that typed code |
sandbox_egress_all_cooling | every egress address is cooling down for the model (§3); nothing was booted |
device_offline | the 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):
| Verdict | Meaning |
|---|---|
ok | the box passes this check |
ko | the box demonstrably cannot do it; carries the same failure class a live turn would (usage-limit, rate-limit, ...) |
unknown | the 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_invalidbefore 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 withsandbox_preflight_failed(runtime/src/session-spawn.ts:7863-7880), whosedetailscarryprobe,errorClass,probeDetail,egressIp,provider,sandboxIdand the fulloutcomeslist (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 okto 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
opencodeharness only. Any other harness yieldsunknown(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). korequires a classified failure. A non-zero exit or an empty answer is held to the full classification; a zero-exit answer iskoonly 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):
errorClass | Default cooldown |
|---|---|
usage-limit | 60 min |
rate-limit | 10 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:
- a preflight
kowith classusage-limitorrate-limithappens on a box that reports a public address, for a spawn that names a model (runtime/src/session-spawn.ts:7849-7862); - a live turn of a sandboxed session ends in an error classified
usage-limitorrate-limit, whatever the session's ownturnRetrypolicy opted into; aretry-afterhint on a rate limit sets the duration (runtime/src/turn-retry.ts:1296-1314); - 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,untilanderrorClass(sandbox/src/agent-session-host.ts:338-375,runtime/src/session-spawn.ts:7657-7667); - falls back to the controller's own
autowhen 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 | |
|---|---|---|
| When | before the agent starts | after a turn failed on a live session |
| Moves | to another sandbox (and the rung's model, access) | same session: retry, rotate the model, apply a fallback overlay, or migrate to a fresh box |
| Trigger | typed 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
modelis metered, and a rung or top-levelturnRetry.fallbackoverlay whosemodelis 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" }
]
}
}- 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). - Rung 2: e2b with the same free model, same probe.
- 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
| Code | Ends the walk | Section |
|---|---|---|
placement_invalid | yes, before any boot | §1 |
sandbox_placement_exhausted | (result of an exhausted walk) | §1 |
sandbox_preflight_invalid | yes | §2 |
sandbox_preflight_failed | no, advances | §2 |
sandbox_egress_all_cooling | no, advances | §3 |
9. Open questions (v1.4)
- Probe coverage.
model-answersonly knows theopencodeharness. Other harnesses answerunknown, so their rungs are never skipped by a probe. egressIpand third-party limits. v1.3 §1 saysegressIpMUST 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.- 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 →
AIP-35: STORAGE (storage/v1): storage policy block
A composable schema block defining the `storage` field — provider, config, sync semantics, auth ref, exclude rules — for any manifest that names a backing store. Reused by WORKSPACE.md (AIP-34) and any future manifest that names persistent state. Inline or ref, mirroring AIP-17 RUNNER and AIP-19 SECRETS.
AIP-37: LIFECYCLE (lifecycle/v1): event vocabulary
A vocabulary AIP defining the standard lifecycle event names that hosts fire and that policy blocks (storage sync, sandbox lifecycle, etc.) reference. Not a runtime — just a shared language so configs across hosts mean the same thing.