# Provider catalog

Select the Agent, Sandbox, and Workspace adapters that own each AML execution boundary.
Canonical: https://agent-markup-language.com/docs/providers/
Documentation index: https://agent-markup-language.com/docs/
Complete documentation: https://agent-markup-language.com/docs/llms.txt

AML providers are adapters around three independent responsibilities. Select one provider for each boundary your workflow uses; a tree that only runs an Agent does not need a Sandbox or Workspace.

**Runtime architecture — one authored tree, three explicit boundaries**

1. [Agent](https://agent-markup-language.com/docs/providers/agents/) — model session, turns, tools, and protocol translation.
2. [Sandbox](https://agent-markup-language.com/docs/providers/sandboxes/) — commands, filesystem access, process lifetime, and cleanup.
3. [Workspace](https://agent-markup-language.com/docs/providers/workspaces/) — materialization, durable revisions, locks, and save policy.

## Choose by responsibility

| Layer         | Owns                                                                              | Does not own                                               |
| ------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Agent**     | Model sessions, turns, native tools, ACP launch and protocol translation          | Process or filesystem isolation unless a Sandbox is active |
| **Sandbox**   | Ephemeral commands, process lifetime, filesystem access, cancellation and cleanup | Durable revisions or model credentials                     |
| **Workspace** | Materialization, durable files, revisions, locking and save policy                | Command isolation or Agent behavior                        |

**Note — Provider-independent does not mean capability-identical**

AML normalizes the orchestration contract, but providers retain meaningful differences: supported tools, permission
translation, read-only behavior, executable requirements, cancellation semantics, persistence formats, and failure
modes. Read the detail page before treating two adapters as interchangeable.

## A direct selection rule

1. Pick an **Agent** only when the work needs a model or coding-harness session.
2. Add a **Sandbox** when that Agent or a Script must execute processes in a deliberate host, container, or remote boundary.
3. Add a **Workspace** when files need durable identity, sharing, revision publication, or conflict control across evaluations.

For a first workflow, begin with [`DeterministicAgentProvider`](https://agent-markup-language.com/docs/reference/testing/#deterministicagentprovider). Move to one live Agent, then add a Sandbox, and add durable Workspace storage last. Each step introduces a separate credential, failure, and cleanup surface that should earn its place.

## Current built-ins

**Agent providers**

- [Codex](https://agent-markup-language.com/docs/providers/agents/codex/) — Codex coding workflows through `codex-acp`.
- [GitHub Copilot](https://agent-markup-language.com/docs/providers/agents/copilot/) — Copilot CLI model access through native `copilot --acp`.
- [OpenCode](https://agent-markup-language.com/docs/providers/agents/opencode/) — open-source model access through OpenCode ACP.
- [Pi](https://agent-markup-language.com/docs/providers/agents/pi/) — extensible Pi harnesses through `pi-acp`.

**Sandbox providers**

- [Local](https://agent-markup-language.com/docs/providers/sandboxes/local/) — trusted host development; no isolation boundary.
- [Docker](https://agent-markup-language.com/docs/providers/sandboxes/docker/) — disposable container work.
- [Daytona](https://agent-markup-language.com/docs/providers/sandboxes/daytona/) — remote development environments.
- [Modal](https://agent-markup-language.com/docs/providers/sandboxes/modal/) — serverless remote execution.

**Workspace providers**

- [Local](https://agent-markup-language.com/docs/providers/workspaces/local/) — one existing durable directory.
- [Filesystem](https://agent-markup-language.com/docs/providers/workspaces/filesystem/) — local archive or folder revisions.
- [S3](https://agent-markup-language.com/docs/providers/workspaces/s3/) — S3-compatible shared durable history.

All factories above are exported from `@aml-jsx/sdk` and installed with the SDK.

## Practical starting points

**Credential-free learning**

Use [`DeterministicAgentProvider`](https://agent-markup-language.com/docs/reference/testing/#deterministicagentprovider) from `@aml-jsx/sdk/testing`.
It records normalized calls and avoids network or executable setup.

**Trusted local automation**

Pair an Agent with [`localSandbox()`](https://agent-markup-language.com/docs/providers/sandboxes/local/) and
[`localWorkspace()`](https://agent-markup-language.com/docs/providers/workspaces/local/) only when the workflow and every generated command are
trusted on the host.

**Disposable container work**

Use Docker with an image that already contains the selected ACP executable. Add your own hardening for network,
users, capabilities, resources, and daemon exposure.

**Durable remote workflows**

Combine Daytona or Modal with [`filesystemWorkspace()`](https://agent-markup-language.com/docs/providers/workspaces/filesystem/) or
[`s3Workspace()`](https://agent-markup-language.com/docs/providers/workspaces/s3/) when disposable execution must load and publish revision-backed
state.

## Selection checklist

Before evaluating a provider-backed workflow, verify:

1. The Agent executable exists in the host, image, snapshot, or remote environment where AML will launch it.
2. Required vendor credentials are available to that executable without being embedded in authored prompts or persisted files.
3. The Agent provider reports compatibility with the effective Sandbox runtime.
4. Sandbox `access`, `root`, and `cwd` semantics match the provider's actual enforcement.
5. Workspace `load`, `save`, locking, retention, and cancellation behavior match your durability requirements.
6. Cleanup and telemetry failures are visible to production operators.

Continue to the [Agent](https://agent-markup-language.com/docs/providers/agents/), [Sandbox](https://agent-markup-language.com/docs/providers/sandboxes/), or [Workspace](https://agent-markup-language.com/docs/providers/workspaces/) comparison, or read [Production security](https://agent-markup-language.com/docs/production/security/) before running untrusted work.

Adding an integration instead of selecting a built-in? Start with [Provider engineering](https://agent-markup-language.com/docs/provider-authoring/) to choose the extension boundary, then use the exact [Provider authoring reference](https://agent-markup-language.com/docs/reference/provider-authoring/) while implementing it.