Provider catalog

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 architectureOne authored tree, three explicit boundaries

<Workspace><Sandbox><Agent /></Sandbox></Workspace>resolves into

01AgentModel session, turns, tools, and protocol translation02SandboxCommands, filesystem access, process lifetime, and cleanup03WorkspaceMaterialization, 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

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. 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

Own model sessions, native capabilities, and the Agent Client Protocol lifecycle.

CodexACP · codex-acpCodex coding workflows↗OpenCodeACP · opencodeOpen source model access↗PiACP · pi-acp + piExtensible agent harnesses↗

Sandbox providers

Own process execution, filesystem isolation, and ephemeral environment cleanup.

LocalHost process · no isolationTrusted development↗DockerDocker CLI + daemonDisposable container work↗DaytonaDaytona credentialsRemote dev environments↗ModalModal credentialsServerless remote work↗

Workspace providers

Own durable files, revision storage, locking, and materialization into a runtime.

LocalExisting directory · direct writesTrusted local state↗FilesystemArchive or folder revisionsLocal durable history↗S3S3-compatible object storageShared durable history↗

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

Practical starting points

Credential-free learning

Use DeterministicAgentProvider from @aml-jsx/sdk/testing. It records normalized calls and avoids network or executable setup.

Trusted local automation

Pair an Agent with localSandbox() and localWorkspace() 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() or s3Workspace() 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, Sandbox, or Workspace comparison, or read Production security before running untrusted work.

Adding an integration instead of selecting a built-in? Start with Provider engineering to choose the extension boundary, then use the exact Provider authoring reference while implementing it.