# 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/) — `codexAgent()`. ACP · codex-acp; Codex coding workflows.
- [GitHub Copilot](https://agent-markup-language.com/docs/providers/agents/copilot/) — `copilotAgent()`. ACP · copilot --acp; Copilot CLI model access.
- [GLM](https://agent-markup-language.com/docs/providers/agents/glm/) — `glmAgent()`. ACP · glm-acp-agent; Z.ai Coding Plan models.
- [OpenCode](https://agent-markup-language.com/docs/providers/agents/opencode/) — `opencodeAgent()`. ACP · opencode; Open source model access.
- [Pi](https://agent-markup-language.com/docs/providers/agents/pi/) — `piAgent()`. ACP · pi-acp + pi; Extensible agent harnesses.

**Sandbox providers**

- [Local](https://agent-markup-language.com/docs/providers/sandboxes/local/) — `localSandbox()`. Host process · no isolation; Trusted development.
- [Docker](https://agent-markup-language.com/docs/providers/sandboxes/docker/) — `dockerSandbox()`. Docker CLI + daemon; Disposable container work.
- [Daytona](https://agent-markup-language.com/docs/providers/sandboxes/daytona/) — `daytonaSandbox()`. Daytona credentials; Remote dev environments.
- [Modal](https://agent-markup-language.com/docs/providers/sandboxes/modal/) — `modalSandbox()`. Modal credentials; Serverless remote work.

**Workspace providers**

- [Local](https://agent-markup-language.com/docs/providers/workspaces/local/) — `localWorkspace()`. Existing directory · direct writes; Trusted local state.
- [Filesystem](https://agent-markup-language.com/docs/providers/workspaces/filesystem/) — `filesystemWorkspace()`. Archive or folder revisions; Local durable history.
- [S3](https://agent-markup-language.com/docs/providers/workspaces/s3/) — `s3Workspace()`. S3-compatible object storage; 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.