<Sandbox />

<Sandbox /> enters a provider-owned execution environment before evaluating its descendants and releases the lease after the subtree settles. Choose a Sandbox provider whose isolation and deployment model match the work.

import { Agent, AmlRuntime, Sandbox } from "@aml-jsx/sdk"
import { DeterministicAgentProvider, DeterministicSandboxProvider } from "@aml-jsx/sdk/testing"

const agent = new DeterministicAgentProvider({ supportsSandbox: () => true })
const sandbox = new DeterministicSandboxProvider()
const runtime = new AmlRuntime({ agentProvider: agent, sandboxProvider: sandbox })

await runtime.evaluate(
  <Sandbox access="read-only" root="repository">
    <Agent cwd="src">Inspect the project without modifying files.</Agent>
  </Sandbox>
)

The deterministic providers make this example credential-free. For actual process execution, use Local, Docker, Daytona, or Modal.

Images and providers

<Sandbox /> expresses portable execution intent: provider, access, logical root, cwd, and descendants. It does not have an image prop. The outer Sandbox provider owns the physical environment:

localSandbox() runs trusted processes on the AML host and uses no image;
dockerSandbox() starts a local container from an OCI image;
daytonaSandbox() creates a remote environment from an OCI image or Daytona snapshot;
modalSandbox() creates a remote environment from a registry image.

Docker, Daytona, and Modal use wearesingular/aml-agent-sandbox:latest when their factory receives no image or snapshot override. The default contains AML’s tested Agent executables and common coding tools. It does not contain application credentials or project-specific dependencies.

That default comes from AML’s canonical releases on Docker Hub. The repository smoke matrix uses the separate, mutable ghcr.io/we-are-singular/aml-agent-sandbox:dev build from main.

const sandbox = dockerSandbox()

await runtime.evaluate(
  <Sandbox provider={sandbox} access="read-write">
    <Agent>Inspect the project.</Agent>
  </Sandbox>
)

Configure an immutable or application-owned image on the provider factory when required:

const sandbox = dockerSandbox({
  image: "wearesingular/aml-agent-sandbox:X.Y.Z",
})

The image supplies software; the provider supplies process transport, Workspace mapping, cancellation, and cleanup; the application still supplies credentials, network and resource policy, project dependencies, and deployment hardening. Read AML Agent Sandbox images for variants, registry channels, exact contents, pinning, and extension guidance. Use alternative and custom images when replacing AML’s image.

Props

Prop	Type	Default	Meaning
`children`	`AmlRenderable`	empty	Values evaluated inside the active lease.
`provider`	`SandboxProvider`	runtime `sandboxProvider`	Provider for the outermost Sandbox.
`access`	`"read-only" \| "read-write"`	`"read-only"`	Portable filesystem authority requested from the provider.
`root`	`string`	`"."`	Logical root visible to descendants.
`cwd`	`string`	Workspace cwd, root, or `"."`	Logical default working directory within `root`.

Nesting

A nested <Sandbox /> reuses the outer lease. It may narrow root, change cwd within that root, or narrow read-write to read-only. It cannot select another provider, acquire another lease, escape the parent root, or widen read-only access.

<Sandbox provider={sandbox} access="read-write" root="repository">
  <Sandbox access="read-only" root="packages/api">
    <Agent cwd="src">Inspect this package.</Agent>
  </Sandbox>
</Sandbox>

Descendant behavior

A descendant <Script /> executes only through the active Sandbox runtime; it never falls back to the host from inside this scope. Its optional cwd resolves from this Sandbox’s effective root.
A compatible <Agent /> receives the effective Sandbox session; its native permissions cannot widen it.
An enclosing <Workspace /> supplies the materialized directory. The Sandbox provider maps logical paths into its host, container, or remote environment.
<File /> writes through the live guest filesystem and therefore requires access="read-write".
<Include path> reads the live guest filesystem. <Include src> and <File src> still read their application-owned source from the runtime cwd before copying or rendering it.
<Skill /> and oversized local Includes use a separate writable Agent staging root even when the live guest filesystem is read-only.

See Run AML in a Sandbox image, Sandbox and Workspace composition, compatibility, and production security.