# <Sandbox />

Acquire an ephemeral execution lease and scope a filesystem policy and logical working directory to descendants.
Canonical: https://agent-markup-language.com/docs/reference/primitives/sandbox/
Documentation index: https://agent-markup-language.com/docs/
Complete documentation: https://agent-markup-language.com/docs/llms.txt

`<Sandbox />` enters a provider-owned execution environment before evaluating its descendants and releases the lease after the subtree settles. Choose a [Sandbox provider](https://agent-markup-language.com/docs/providers/sandboxes/) whose isolation and deployment model match the work.

```tsx
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](https://agent-markup-language.com/docs/providers/sandboxes/local/), [Docker](https://agent-markup-language.com/docs/providers/sandboxes/docker/), [Daytona](https://agent-markup-language.com/docs/providers/sandboxes/daytona/), or [Modal](https://agent-markup-language.com/docs/providers/sandboxes/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`.

```tsx title="Use AML's default image"
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:

```ts
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](https://agent-markup-language.com/docs/sandbox-images/) for variants, registry channels, exact contents, pinning, and extension guidance. Use [alternative and custom images](https://agent-markup-language.com/docs/providers/sandboxes/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.

```tsx
<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 />`](https://agent-markup-language.com/docs/reference/primitives/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 />`](https://agent-markup-language.com/docs/reference/primitives/agent/) receives the effective Sandbox session; its native permissions cannot widen it.
- An enclosing [`<Workspace />`](https://agent-markup-language.com/docs/reference/primitives/workspace/) supplies the materialized directory. The Sandbox provider maps logical paths into its host, container, or remote environment.
- [`<File />`](https://agent-markup-language.com/docs/reference/primitives/file/) writes through the live guest filesystem and therefore requires `access="read-write"`.
- [`<Include path>`](https://agent-markup-language.com/docs/reference/primitives/include/) reads the live guest filesystem. [`<Include src>`](https://agent-markup-language.com/docs/reference/primitives/include/) and `<File src>` still read their application-owned source from the runtime cwd before copying or rendering it.
- [`<Skill />`](https://agent-markup-language.com/docs/reference/primitives/skill/) and oversized local Includes use a separate writable Agent staging root even when the live guest filesystem is read-only.

**Caution — Provider names do not prove isolation**

[`localSandbox()`](https://agent-markup-language.com/docs/providers/sandboxes/local/) is trusted host execution. Docker, Daytona, and Modal have
different containment, identity, network, image, and resource controls. Read the selected provider guide and validate
your deployment before running untrusted work.

See [Run AML in a Sandbox image](https://agent-markup-language.com/docs/cookbook/sandbox-image/), [Sandbox and Workspace composition](https://agent-markup-language.com/docs/cookbook/sandboxes-and-workspaces/), [compatibility](https://agent-markup-language.com/docs/compatibility/), and [production security](https://agent-markup-language.com/docs/production/security/).