Production readiness

AML can execute ordinary host processes, disposable containers, or remote Sandboxes and can persist Workspaces locally or in object storage. Production readiness therefore depends on the combination of providers, the credentials they receive, and the effects your workflow is allowed to perform.

This section is a set of production guidance pages, not a generic security certification. Read the provider caveats before selecting an execution boundary.

Choose the right page

You need to…	Read
establish a threat model and protect credentials	Security
package AML into a service, worker, or job	Deployment
operate retries, cancellation, locks, and traces	Operations
diagnose a live cleanup, lock, publication, or trace failure	Incident response
understand the provider-specific trade-offs	Sandbox providers and Workspace providers
understand how AML provider adapters are structured	Provider engineering
implement a new adapter against the public TypeScript API	Provider authoring reference

The production topology

application process
  ├─ AmlRuntime: limits, cancellation, traces, scheduling
  ├─ Agent provider: model harness and session protocol
  ├─ Sandbox provider: process environment and execution policy
  └─ Workspace provider: materialization, locking, revisions, persistence
                    │
                    ├─ local host directory
                    ├─ Docker bind mount
                    └─ remote Sandbox + transferred Workspace

AML does not make these four responsibilities interchangeable. An Agent can be provider-neutral at the authored boundary while still requiring a particular executable, image, model credential, or Sandbox runtime. A remote Sandbox may make execution ephemeral while the Workspace remains durable. A local Workspace may persist directly in the application’s filesystem without creating a revision history.

Grow the deployment one boundary at a time

Stage	Add	What you prove before moving on
Deterministic workflow	Testing provider and ordinary TypeScript policy	Tree shape, dataflow, schemas, budgets, and expected application output.
Live Agent	One coding harness, model, and credential path	Executable discovery, authentication, capability translation, and cancellation.
Ephemeral execution	Docker, Daytona, or Modal Sandbox	Image contents, cwd mapping, process cleanup, access, and resource/network policy.
Durable state	Local, Filesystem, or S3 Workspace	Materialization, conflicts, save policy, publication, retention, and recovery.
Production job	Request deadlines, identity, redacted telemetry, and retry policy	The exact complete graph survives failure and cleanup paths.

Do not introduce all three provider boundaries to debug a first Agent call. Each stage has an independently observable contract and failure surface.

A deployable runtime baseline

The runtime defaults include bounded Agent calls and concurrency, depth and Loop limits, and a trace sink that excludes sensitive content unless a consumer explicitly opts in. Set the values deliberately for your workload and pass cancellation per evaluation.

import {
  Agent,
  AmlRuntime,
  Sandbox,
  Workspace,
  codexAgent,
  createConsoleTracer,
  dockerSandbox,
  s3Workspace,
} from "@aml-jsx/sdk"

function requireEnv(name: string): string {
  const value = process.env[name]
  if (!value) throw new Error(`${name} is required`)
  return value
}

const runtime = new AmlRuntime({
  agentProvider: codexAgent({ apiKey: requireEnv("OPENAI_API_KEY") }),
  sandboxProvider: dockerSandbox({
    image: requireEnv("AML_AGENT_IMAGE"),
  }),
  workspaceProvider: s3Workspace({
    bucket: requireEnv("AML_WORKSPACE_BUCKET"),
    prefix: "production/workspaces",
  }),
  maxAgentCalls: 32,
  maxConcurrentAgents: 4,
  maxTurnsPerAgent: 8,
  trace: createConsoleTracer({ captureContent: false }),
})

const workflow = (
  <Workspace id="review-42" load={false} save={{ on: "success", retention: 5 }}>
    <Sandbox access="read-write">
      <Agent>Review the materialized project and write reports/summary.md.</Agent>
    </Sandbox>
  </Workspace>
)

const controller = new AbortController()
const stop = setTimeout(() => controller.abort(new Error("request deadline exceeded")), 120_000)

try {
  await runtime.evaluate(workflow, { signal: controller.signal })
} finally {
  clearTimeout(stop)
}

This is a wiring example, not a claim that the image or credentials are ready. The image must contain the selected ACP executable and its dependencies; the object-storage identity must have the permissions required by the S3 Workspace protocol; and the application must decide whether model-generated actions are trusted.

Readiness gates

Before production traffic, verify each gate with the exact provider combination you will deploy:

Identity — credentials are injected by the workload identity or secret manager, not written into prompts, Workspaces, images, or setup strings.
Execution — the selected Sandbox has the required shell, utilities, ACP executable, model configuration, network policy, and resource limits.
Persistence — the Workspace’s load, save, lock, retention, and conflict behavior matches the retry and concurrency model.
Cancellation — request deadlines abort evaluation work; providers attempt cleanup, which may continue after cancellation and can itself fail. Confirm process, temporary-directory, remote-Sandbox, and lock outcomes.
Observability — traces correlate a run and its spans without capturing customer content by default; provider and cleanup failures reach an operational sink.
Recovery — retries distinguish active-writer conflicts, stale conditional publication, provider outages, model failures, and completed external side effects.

Support and maturity

The current providers are shipped built-ins in a pre-stable SDK. “Built-in” does not mean every combination has identical capabilities or that a vendor environment is continuously certified. Check the provider pages for requirements and compatibility:

Agent providers use ACP for the built-in coding-agent integrations.
Sandbox providers differ in read-only behavior, transfer semantics, cancellation, and deployment-owned security posture.
Workspace providers differ in direct materialization versus revision-backed persistence.

Treat a provider combination as production-ready only after exercising its actual image, credentials, network, filesystem, and failure paths. An adapter that passes structural validation has proved its API shape; it has not proved vendor availability, credentials, or a hostile-code threat model. The compatibility guide defines the narrower evidence labels used throughout these docs.