Daytona Sandbox

Sandbox provider

daytonaSandbox(options?)

The Daytona provider creates a disposable remote Sandbox, uploads the selected Workspace into the provider’s relative workspace directory, and reconciles the full tree on writable release.

Best for

Remote development environments where Daytona owns provisioning and lifecycle.

Know before using

The Workspace is transferred, not mounted. Remote edits can be lost if acquisition, execution, or reconciliation fails before the tree is downloaded.

When to use it

Choose Daytona when you want Daytona-managed remote environments and are prepared to provide its credentials/client and validate the selected image or snapshot. It is a transfer-based provider: AML archives the local Workspace, uploads it, runs the workflow remotely, downloads the complete remote tree on writable release, and then destroys the Sandbox.

Daytona starts commands in the Sandbox user’s writable home. AML therefore uses the relative guest root workspace, not /workspace. The absolute location of that relative directory is provider/runtime dependent; do not hard-code filesystem-root assumptions into Agent prompts.

Options

Option	Type	Default	Contract
image	Daytona image reference	wearesingular/aml-agent-sandbox:latest	Selects image-based creation. Mutually exclusive with snapshot; may be omitted.
snapshot	Daytona snapshot reference	None	Selects snapshot-based creation. Mutually exclusive with image; may be omitted.
client	Daytona	None	Inject an initialized Daytona client. Mutually exclusive with config.
config	DaytonaConfig	None	Configuration used to construct a Daytona client lazily.
create	Provider-native create fields	None	Additional creation parameters. Must not contain image or snapshot; those are AML root options.
createOptions	{ timeout?, onSnapshotCreateLogs? }	None	Daytona creation timeout and optional snapshot-create log callback.
maxOutputBytes	number	4 * 1024 * 1024	Shared output/transfer budget. Must be a positive safe integer.
setup	string	None	Runs through sh -lc after hydration and before the lease is returned.
workspace	string	None	Fallback local Workspace path. An active <Workspace /> materialization takes precedence.

image and snapshot are mutually exclusive, but both may be omitted. With neither root option, AML selects the full wearesingular/aml-agent-sandbox:latest image. Choose and pin a full or single-Agent release with the AML image guide. Do not put either field inside create; the provider rejects that configuration to keep environment identity explicit.

Network egress and firewall tiers

Confirm outbound access for the selected Agent

Daytona applies network access according to the organization tier. Tier 1 and Tier 2 use Daytona’s managed essential-services allowlist, while Tier 3 and Tier 4 support custom Sandbox network settings. If an Agent requires an endpoint outside the effective policy, its model connection may fail. Review the required Agent domains and test them from the deployed Sandbox before a live run.

Organization tier	Daytona network behavior	Sandbox configuration
Tier 1 or Tier 2	Access to Daytona’s managed essential services	Per-Sandbox domainAllowList and networkAllowList settings cannot expand the organization policy.
Tier 3 or Tier 4	Full internet access by default	Custom network rules can restrict access to the domains and networks required by the workload.

AML passes provider-native network fields through create; it does not alter Daytona’s organization-level policy. Before running a production Agent image, identify its outbound endpoints and test them from the same Daytona Sandbox. For Tier 1/2, compare those endpoints with the managed essential-services list. For Tier 3/4, review any custom firewall configuration and allow only the domains required by the workload.

See Daytona’s published network limits and essential services for the tier contract. The currently proposed additions are visible in the updated whitelist file.

Remote image and environment requirements

The selected image or snapshot must provide:

• a shell capable of running AML’s quoted setup/transfer commands;
• tar, mkdir, and rm for Workspace hydration and reconciliation;
• the selected ACP Agent executable and its runtime, if an Agent runs inside Daytona;
• project dependencies and model/provider configuration;
• a writable home/workspace area for the selected user.

The host running AML also needs the local tar command because upload and download archives are created/extracted locally. The Daytona client/config must have permissions to create, inspect, upload to, download from, and delete the disposable Sandbox.

Workspace semantics

Daytona resolves the active Workspace directory or workspace fallback, then uses the logical Sandbox root as the source subtree. The source must be an existing directory. cwd must resolve inside that root.

The provider uploads an archive and extracts it into the guest directory workspace. At release, writable access causes a full archive of that guest tree to be downloaded and mirrored into the local materialization, including additions, modifications, and deletions. Read-only access skips reconciliation.

This is full-tree synchronization, not continuous sync. If the remote Sandbox dies before reconciliation, unsynchronized edits are not recoverable through AML. Use a durable Workspace provider or an explicit checkpoint strategy when that loss is unacceptable.

Complete safe example

This deterministic example uses a temporary Workspace and a Daytona image that only needs shell utilities. A real Agent image must additionally contain its ACP executable and credentials:

/** @jsxImportSource @aml-jsx/sdk */
import { mkdtemp } from "node:fs/promises"
import { join } from "node:path"
import { tmpdir } from "node:os"
import { AmlRuntime, Sandbox, Script, Workspace, daytonaSandbox, localWorkspace } from "@aml-jsx/sdk"

const directory = await mkdtemp(join(tmpdir(), "aml-daytona-"))
const runtime = new AmlRuntime({
  sandboxProvider: daytonaSandbox({
    image: "daytona/image-with-shell-and-tar",
    // Or use snapshot: "my-agent-snapshot"; never set both.
    config: { apiKey: process.env.DAYTONA_API_KEY },
  }),
  workspaceProvider: localWorkspace({ directory }),
})

await runtime.evaluate(
  <Workspace id="daytona-demo" load={false} save={false}>
    <Sandbox access="read-write">
      <Script command="sh" args={["-lc", "printf remote > result.txt"]} />
    </Sandbox>
  </Workspace>
)

The image name above is illustrative: select an image that Daytona can resolve or a snapshot from your Daytona account. Never commit DAYTONA_API_KEY; configure it through the deployment environment or an injected Daytona client.

Lifecycle

1. AML resolves the active/fallback Workspace source and validates root/cwd boundaries.
2. Daytona creates a Sandbox using the selected image or snapshot; omitting both uses AML’s default image. createOptions.timeout applies to creation; onSnapshotCreateLogs receives provider-native snapshot creation logs.
3. AML creates a local tar archive of the selected Workspace tree and uploads it to a temporary remote path.
4. Daytona runs a remote command that clears workspace, creates it, extracts the archive, and removes the temporary archive.
5. The optional setup hook runs through sh -lc. Failure rejects acquisition and destroys the Sandbox.
6. exec() and spawn() operate below the relative workspace root. Process timeouts are converted to provider-native seconds; output is bounded.
7. Complete-file operations use Daytona’s filesystem API. Agent staging uses a unique /tmp directory and is removed before Sandbox release.
8. On writable release, Daytona archives the complete remote workspace tree, downloads it, and mirrors additions, changes, and deletions into the local source.
9. Daytona destroys the Sandbox. Reconciliation and cleanup errors are both retained when both fail.

Cancellation during creation or hydration can trigger asynchronous provider cleanup. Cancellation or output overflow during a remote command can destroy the disposable Sandbox because Daytona does not provide equivalent per-command cancellation for every operation.

Read-only behavior

Daytona rejects exec() and spawn() under access="read-only". The Workspace is transferred into a writable remote directory; it is not a read-only mount. This is an intentional limitation, not a promise that commands execute safely without changing the remote tree.

Use read-write for a Daytona ACP Agent unless the complete Agent/Sandbox contract you selected provides another supported launch path. A read-only Daytona Sandbox can serve live <Include path> reads and writable invocation-private Agent staging, but it cannot run ordinary <Script /> components or ACP sessions because those require process execution.

Failure modes and troubleshooting

Symptom	Cause	What to check
image and snapshot rejected together	Environment identity is ambiguous.	Choose exactly one, or omit both for AML’s default image.
image/snapshot inside create rejected	AML keeps root identity separate from native creation fields.	Move the field to the factory root.
requires an active Workspace or configured workspace	No source tree was provided.	Add <Workspace /> or a workspace fallback.
tar transfer fails locally	Host tar is missing, the source is inaccessible, or archive output exceeded the budget.	Run tar -C <source> -cf /tmp/check.tar . as the AML user.
Hydration fails remotely	Image lacks sh, tar, mkdir, rm, or a writable home.	Open a Daytona shell with the same image/user and verify utilities.
Agent command not found	The image/snapshot does not contain the ACP executable.	Install and pin it in the image/snapshot; AML does not install it.
Agent API resets during TLS	A required endpoint is outside the effective Daytona network policy.	Compare the endpoint with the managed whitelist or the Sandbox’s custom network settings, then test it from that Sandbox.
cannot execute under read-only access	Transferred Workspaces cannot enforce read-only process execution.	Use read-write or a different provider.
Remote changes disappear	The Sandbox failed before writable reconciliation completed.	Use checkpoints/durable persistence and inspect Daytona lifecycle logs.
Reconciliation fails	Remote archive creation/download or local extraction failed.	Check remote tar, local disk space, output limits, and Workspace permissions.
Cleanup fails after another error	Provider failure and destruction failure occurred together.	Inspect the aggregate error and Daytona account/Sandbox state.

Security and production posture

Daytona provides a remote execution environment, but AML’s adapter does not define your complete threat model. Review the selected image, user identity, network egress, secrets, account permissions, and provider isolation. Keep credentials in Daytona/provider configuration rather than Workspace files. Treat setup as trusted configuration and prefer a reproducible image or snapshot for repeated production workloads.

Because transfer is full-tree and release-time, a provider outage can lose remote changes not yet reconciled. For important work, pair the Sandbox with a revision-backed Workspace provider and define what should happen when reconciliation or cleanup fails.

References

• Sandbox provider overview
• Daytona documentation
• Daytona network limits and essential services
• Updated Daytona whitelist file
• AML Daytona provider implementation
• AML Daytona provider tests
• Sandboxing architecture
• AML specification: Sandbox composition