Daytona Sandbox Provider

The Daytona backend prepares a remote sandbox, syncs workspace files, opens the provider tool host, and starts the ACP agent through AGH's sandbox launcher.

Rendering diagram...

The Daytona provider creates or reuses a remote runtime, syncs workspace files, launches the agent, and applies the configured persistence mode.

Required credential

Set DAYTONA_API_KEY in the daemon environment before starting AGH:

export DAYTONA_API_KEY="..."
agh daemon start

The key is used by the Daytona SDK and SSH access flow. Do not put the raw token in session prompts, channel messages, logs, or extension payloads.

AGH requests Daytona SSH access during launch. The credential belongs in the daemon environment, not in config.toml, because config can be printed, edited, and shared by agents.

Profile example

[sandboxes.daytona-dev]
backend = "daytona"
sync_mode = "session-bidirectional"
persistence = "reuse"
runtime_root = "/home/daytona/workspace"

[sandboxes.daytona-dev.daytona]
api_url = "https://app.daytona.io/api"
target = "team-default"
snapshot = "snap-agent-base"
image = "ubuntu:24.04"
class = "cpu-2"
auto_stop = "30m"
auto_archive = "24h"

Field	Purpose
`api_url`	Daytona API base URL. Defaults to `https://app.daytona.io/api`.
`target`	Daytona target or organization routing value.
`snapshot`	Preferred startup source when present.
`image`	Image startup source when `snapshot` is empty.
`class`	Provider class metadata passed with the profile.
`auto_stop`	Daytona auto-stop interval.
`auto_archive`	Daytona auto-archive interval.

Run a workspace in Daytona

agh workspace add /Users/you/project --name project --sandbox daytona-dev
agh session new --workspace project --agent general
agh session status <session-id> -o json

The session payload includes a sandbox object with backend, profile, provider instance, state, and sync details.

Persistence

Value	Behavior
`transient`	Delete the Daytona sandbox when AGH stops the session.
`archive`	Archive the sandbox on stop.
`reuse`	Leave the sandbox available for reattachment.

Daemon restart reconciliation uses sandbox_id, provider state, and Daytona labels to reattach or clean up recoverable remote sandboxes.

Verify the run

Evidence	Command	What it proves
Workspace selected Daytona	`agh workspace info project -o json`	The workspace resolves `daytona-dev`.
Session prepared remotely	`agh session status <session-id> -o json`	The `sandbox.backend` is `daytona` and has an `instance_id`.
Sync occurred	`agh session events <session-id> --last 50 -o json`	`sandbox.sync.*` events include direction and reason.
Agent actually produced work	`agh session history <session-id>`	The remote ACP process emitted turns, tool calls, or output.
Persistence matched intent	Session status after stop	The sandbox state aligns with `transient`, `archive`, or `reuse`.

Troubleshooting

Symptom	Check first	Likely fix
Prepare fails before sync	Daemon environment	Set `DAYTONA_API_KEY` before `agh daemon start`.
Daytona creates a new sandbox each run	`persistence` and provider labels in status	Use `persistence = "reuse"` when reattachment is desired.
Remote workspace is empty	`runtime_root`, sync rules, and sync events	Point `runtime_root` at the expected remote path and narrow excludes.
Session hangs after prepare	`sandbox.transport.*` events and daemon logs	Check Daytona SSH access and sidecar launch health.
Files did not return to the host	`sandbox.sync.*` events with `from_runtime`	Confirm the session reached stop/crash handling and sync-back ran.

Sandbox Profiles covers shared profile fields and resolution order.
Sandbox Overview explains the local and remote sandbox lifecycle.
Session Events lists where sandbox prepare, sync, and stop events appear.
Operations Troubleshooting gives daemon-level checks when a sandbox-backed session fails before agent startup.