Sandbox
What a sandbox adapter (e2b(), daytona(), modal(), fakeSandbox()) returns.
Every create and restore carries an operation key written to the resource ledger first. Recovery and gc resolve a ledger row only with the adapter whose info.provider is the row's provider; any other adapter is refused before lookup or release, and the row stays unresolved for the right one.
Properties
infoSandboxInforequiredWhat this sandbox provider is and can do: its provider name, egress enforcement, snapshot capture classes, browser and desktop support, lookup capabilities and termination. Read when the agent is pinned.
Methods
create
Create a new isolated sandbox and return its session. Await context.fence() at the provider call; a failed fence returns its code and creates nothing.
create(operationKey: string, context: SandboxContext): Promise<Result<SandboxSession>>operationKey / operation_keystringrequiredThe key the runtime wrote to the resource ledger before this call. Tag the provider resource with it so lookup can find the sandbox if the response is lost.
contextSandboxContextrequiredThe authority to re-check with context.fence() at the provider call. See SandboxContext.
Returns an error value with one of these codes: stale_epoch, cleanup_claim_lost, unavailable, timeout.
restore
Restore a snapshot into a new isolated sandbox and verify it: a restored file tree whose canonical manifest hash isn't manifest_hash is snapshot_manifest_mismatch, and the adapter releases the sandbox it created before returning that error.
restore(snapshotId: string, manifestHash: Sha256, operationKey: string, context: SandboxContext): Promise<Result<SandboxSession>>snapshotId / snapshot_idstringrequiredThe provider's id of the snapshot to restore, from the snapshot event.
manifestHash / manifest_hashSha256requiredThe snapshot event's manifest_hash.
operationKey / operation_keystringrequiredThe key the runtime wrote to the resource ledger before this call. Tag the new sandbox with it, as create does.
contextSandboxContextrequiredThe authority to re-check with context.fence() at the provider call. See SandboxContext.
Returns an error value with one of these codes: stale_epoch, cleanup_claim_lost, snapshot_expired, snapshot_missing, snapshot_restore_failed, snapshot_manifest_mismatch, unavailable.
lookup
Find a sandbox whose create or restore response was lost, by that call's operation key. Resolves the pending ledger row (LookupResult doc). Present when info.lookup.create is not none. A final not_found retires a pending row only when no older local dispatch for that operation_key can still reach the provider; every create and restore fences its SandboxContext at the provider boundary, so once the lease has moved a stale creator can't pass that fence.
lookup(operationKey: string, context: SandboxContext): Promise<Result<LookupResult<SandboxSession>>>operationKey / operation_keystringrequiredThe operation key of the create or restore call whose response was lost.
contextSandboxContextrequiredThe authority to re-check with context.fence() before asking the provider. See SandboxContext.
Returns an error value with one of these codes: stale_epoch, cleanup_claim_lost.
lookupSnapshot / lookup_snapshot
Find a snapshot whose capture response was lost, by the snapshot call's operation key. Resolves the pending ledger row. Present when info.lookup.snapshot is not none.
lookupSnapshot(operationKey: string, context: SandboxContext): Promise<Result<LookupResult<SnapshotEvent.data>>>operationKey / operation_keystringrequiredThe operation key of the snapshot call whose response was lost.
contextSandboxContextrequiredThe authority to re-check with context.fence() before asking the provider. See SandboxContext.
Returns an error value with one of these codes: stale_epoch, cleanup_claim_lost.
attach
Reattach to a live ledger row's sandbox by its recorded ref, so a restarted host can terminate its processes and close it. not_found is final only when info.lookup.create is final; otherwise the answer is resource_unknown and the row becomes unknown.
attach(ref: string, context: SandboxContext): Promise<Result<SandboxSession>>refstringrequiredThe provider's id of the sandbox, as the resource ledger recorded it.
contextSandboxContextrequiredThe authority to re-check with context.fence() before reaching the provider. See SandboxContext.
Returns an error value with one of these codes: stale_epoch, cleanup_claim_lost, not_found, resource_unknown, unavailable.
release
Release a snapshot by its durable ref (ledger row releasing). released or already_gone (the provider proves it no longer exists) → released. An error → release_failed, retried by the next gc, never dropped. Sandboxes are released with SandboxSession.close. v0.1 has no retention holds: a snapshot lives until the provider's declared expiry, and restoring an expired one is snapshot_expired.
release(ref: string, context: SandboxContext): Promise<Result<"released" | "already_gone">>refstringrequiredThe snapshot's provider id, as the resource ledger recorded it.
contextSandboxContextrequiredThe authority to re-check with context.fence() before the release call: the owner's lease, or gc's cleanup claim. See SandboxContext.
Returns an error value with one of these codes: stale_epoch, cleanup_claim_lost, release_failed, unavailable.