Integrations

AML integrations are deliberately compositional. Choose one provider for each responsibility, then check the compatibility and prerequisite contract of the resulting stack.

Start with a complete stack

Local development

import { AmlRuntime, localSandbox, localWorkspace, opencodeAgent } from "@aml-jsx/sdk"

const runtime = new AmlRuntime({
  agentProvider: opencodeAgent({}),
  sandboxProvider: localSandbox(),
  workspaceProvider: localWorkspace({ directory: "/absolute/path/to/project" }),
})

localSandbox() runs trusted host processes. It is appropriate for a developer-owned checkout, not a hostile-code boundary.

Docker execution

import { AmlRuntime, codexAgent, dockerSandbox, localWorkspace } from "@aml-jsx/sdk"

const runtime = new AmlRuntime({
  agentProvider: codexAgent({}),
  sandboxProvider: dockerSandbox(),
  workspaceProvider: localWorkspace({ directory: "/absolute/path/to/project" }),
})

dockerSandbox() defaults to the full wearesingular/aml-agent-sandbox:latest image from AML’s canonical Docker Hub release channel. Stable releases also provide smaller images for each built-in Agent; select the matching image variant when the application always uses one Agent. The repository smoke matrix uses the full ghcr.io/we-are-singular/aml-agent-sandbox:dev image while validating changes from main. Applications can override the default with an immutable version, digest, or custom image containing the compatible ACP executable, project dependencies, credentials strategy, and command-line tools their workflow needs. The provider does not build the image or install an Agent during acquisition.

Durable revisions

import { AmlRuntime, localSandbox, opencodeAgent, s3Workspace } from "@aml-jsx/sdk"

const runtime = new AmlRuntime({
  agentProvider: opencodeAgent({}),
  sandboxProvider: localSandbox(),
  workspaceProvider: s3Workspace({
    bucket: "aml-workspaces",
    prefix: "reviews/",
    config: { region: "us-east-1" },
  }),
})

s3Workspace() needs an S3-compatible client/configuration and storage permissions for its index, revision objects, lock, and cleanup operations.

The integration boundary

Application request
        │
        ▼
AML Runtime ── limits, cancellation, traces, scopes
   │       │       │
   ▼       ▼       ▼
 Agent   Sandbox  Workspace
 ACP     lease    materialization/revision

The Agent provider does not own durable files. The Sandbox provider does not publish revisions. The Workspace provider does not decide which model or ACP executable runs. Keeping those responsibilities separate makes failure and replacement boundaries explicit.

Provider prerequisites

Stack part	Verify before running
Agent	Executable/ACP adapter, credentials, model configuration, provider-specific permissions, and supportsSandbox() compatibility
Sandbox	Provider CLI/SDK, image or snapshot, process APIs, working-directory behavior, output/timeouts, and cleanup permissions
Workspace	Identity, materialization format, lock/revision semantics, storage credentials, save policy, and cleanup permissions
Runtime	Finite limits, allowed Tools/MCP names, cancellation deadline, trace sink, and content handling policy

Credential scope matters

Put credentials in the selected execution environment where possible. A provider factory can carry vendor configuration, but the Sandbox boundary determines which process can read environment variables and files.

A workflow that uses all three

import { Agent, File, Sandbox, Workspace } from "@aml-jsx/sdk"

export function Review() {
  return (
    <Workspace id="review-42" save={{ on: "success" }}>
      <File path="artifacts/review.md">The review is ready.</File>
      <Sandbox access="read-write">
        <Agent system="Return a concise review and a recommended patch plan.">
          Inspect the repository and write the final review.
        </Agent>
      </Sandbox>
    </Workspace>
  )
}

In a real application supply the providers through the runtime or explicit props. <File /> is shown at the <Workspace /> boundary because it persists text through the Workspace provider. Host-backed <Agent /> providers and <Script /> can use trusted local execution; place them inside <Sandbox /> when their processes must run in that selected environment.

Integration checklist

1. Start with a deterministic provider stack to validate tree shape and placement.
2. Select the Agent provider and confirm its executable and credentials in the target environment.
3. Select a Sandbox whose process/filesystem boundary matches the threat model.
4. Add a Workspace only when persistence, sharing, or revision publication is required.
5. Set finite runtime limits and exact Tool/MCP allowlists.
6. Exercise cancellation, provider failure, cleanup, Workspace conflict, and revision recovery.
7. Enable metadata-only tracing by default and review content capture separately.

See the compatibility guide for the supported matrix and provider guides for provider-specific setup.