Skip to main content
Daytona provides cloud-hosted sandbox VMs for Fabro workflows. Each run gets an ephemeral, isolated environment with its own filesystem, network, and compute resources — keeping your host machine clean and giving agents a reproducible workspace.

​
What the Daytona integration enables

FeatureHow it’s used
Sandboxed executionAgent tool calls (shell commands, file edits, grep, glob) run inside a cloud VM instead of on the host
SnapshotsPre-built environment images so each run starts with dependencies already installed
SSH accessConnect to a running sandbox for live debugging
Network controlsRestrict agent egress with block-all or CIDR-based allow lists
MCP sandbox transportRun MCP servers inside the sandbox — e.g., Playwright for browser automation

​
Prerequisites

  • A DAYTONA_API_KEY saved in the Fabro server vault (get one from app.daytona.io)
  • GitHub access configured via the default token strategy or a GitHub App (required for private repository cloning and checkpoint pushing)
The Daytona key must include the snapshot and sandbox scopes Fabro uses to create and clean up environments: write:snapshots, delete:snapshots, write:sandboxes, and delete:sandboxes. Fabro validates these scopes during install, when you run fabro secret set DAYTONA_API_KEY, and in fabro doctor. 
fabro secret set DAYTONA_API_KEY <key>
The Fabro server runtime reads the Daytona API key from the vault only. It does not read DAYTONA_API_KEY from process env or server.env; non-secret Daytona settings such as API URL or organization ID remain normal configuration.

​
Configuration

Select a Daytona environment in your run config TOML or via CLI flag: 
fabro run workflow.fabro --environment cloud
run.toml
[run.environment]
id = "cloud"

[environments.cloud]
provider = "daytona"
A full configuration example with all Daytona-specific options:
run.toml
[run.environment]
id = "cloud"

[environments.cloud]
provider = "daytona"

[environments.cloud.lifecycle]
preserve = false
auto_stop = "60m"

[environments.cloud.labels]
project = "fabro"
env = "staging"
team = "platform"

<Note>
Fabro also adds reserved labels to every managed Daytona sandbox:
`sh.fabro.managed=true` and, when available, `sh.fabro.run_id=<run-id>`.
These match Docker sandbox labels and are useful for filtering provider resources
back to Fabro-managed runs. User-provided values for these reserved keys are
overwritten.
</Note>

[environments.cloud.image]
dockerfile = "FROM rust:1.85-slim-bookworm\nRUN apt-get update && apt-get install -y git ripgrep"
# Or keep the Dockerfile next to this TOML file:
# dockerfile = { path = "./Dockerfile" }

[environments.cloud.resources]
cpu = 4
memory = "8GB"
disk = "20GB"
See Environments for the full reference on all environment fields and server defaults.

​
Network access control

Control outbound network access with the network field. Three modes are available:
run.toml
# Full access (default)
[environments.cloud.network]
mode = "allow_all"

# Block all egress
[environments.cloud.network]
mode = "block"

# CIDR-based allow list
[environments.cloud.network]
mode = "cidr_allow_list"
allow = ["208.80.154.232/32", "10.0.0.0/8"]
Use "block" or a CIDR allow list when running untrusted or generated code to prevent agents from making arbitrary network requests.

​
Snapshots

Snapshots let you pre-build an environment image so each run starts with dependencies already installed rather than installing them in setup commands every time.
run.toml
[environments.cloud.image]
dockerfile = "FROM node:20-slim\nRUN apt-get update && apt-get install -y git"

[environments.cloud.resources]
cpu = 4
memory = 8
disk = 20
When a run starts with image.dockerfile, Fabro computes an internal snapshot name and looks up that snapshot in Daytona. If it doesn’t exist, Fabro creates it automatically and polls until it reaches Active state (up to 10 minutes). dockerfile can be inline content or { path = "..." }; paths are resolved relative to the TOML file that declares them and are bundled into run manifests. If the snapshot already exists, it’s reused immediately.
If no Dockerfile is configured, sandboxes are created from the daytona-medium snapshot which includes standard dev tools (git, etc.). To force a new custom snapshot, change the Dockerfile text, for example by adding a comment.

​
Private repositories

Fabro automatically clones the run’s GitHub origin into the sandbox at /home/daytona/workspace. Public repositories work without extra configuration. Private repositories require GitHub access. In token mode, Fabro uses the stored token directly. In app mode, Fabro uses short-lived Installation Access Tokens scoped to the specific repository. Set [run.clone] enabled = false when a workflow should start with an empty Daytona workspace instead of cloning the run origin:
run.toml
[run.environment]
id = "cloud"

[environments.cloud]
provider = "daytona"

[run.clone]
enabled = false
If the clone fails without GitHub access configured, Fabro suggests running the setup flow: 
Git clone failed: ... If this is a private repository,
run `gh auth login` or `fabro install` to configure GitHub access.

​
SSH access

Connect to a running Daytona sandbox via SSH for live debugging: 
fabro sandbox ssh <run-id>
This creates temporary SSH credentials (valid for 60 minutes) and connects directly. Use --print to print the SSH command instead of connecting, or --ttl to set the credential expiry.
To keep the sandbox alive after the run completes, pass --preserve-sandbox to fabro run.

​
Sandbox lifecycle

Each sandbox gets a unique timestamped name (e.g. fabro-20260307-143022-a3f2) and is created as ephemeral. By default, sandboxes are destroyed when the run finishes.

​
Preservation

To keep a sandbox alive for debugging: 
fabro run workflow.fabro --environment cloud --preserve-sandbox
Or in the run config:
run.toml
[run.environment]
id = "cloud"

[environments.cloud]
provider = "daytona"

[environments.cloud.lifecycle]
preserve = true
When preserved, Fabro prints the sandbox name so you can find it in the Daytona dashboard.

​
Auto-stop

The lifecycle.auto_stop setting tells Daytona to stop the sandbox after a period of inactivity, saving costs for preserved or long-running sandboxes:
run.toml
[environments.cloud.lifecycle]
auto_stop = "30m"

​
Server defaults

When running via fabro server start, the server config at ~/.fabro/settings.toml can set default Daytona settings for all runs. Run config TOML values override server defaults. Labels are merged — run config labels win on key collisions. The network setting uses simple override (run config replaces the server default entirely). See Server Configuration for details.

​
Troubleshooting

​
”Failed to create Daytona sandbox”

The DAYTONA_API_KEY vault secret is missing, invalid, or missing the required snapshot/sandbox scopes. Store it with fabro secret set DAYTONA_API_KEY ..., then run fabro doctor to verify that Daytona reports the key as valid. If doctor reports missing scopes, regenerate the Daytona key with write:snapshots, delete:snapshots, write:sandboxes, and delete:sandboxes, then save it again with fabro secret set DAYTONA_API_KEY.

​
Custom snapshot did not roll

Custom Daytona snapshot names are computed from the Dockerfile, resource hints, tenant scope, and Daytona API key. To force a new custom snapshot, change image.dockerfile text under the selected [environments.<slug>.image].

​
”Timed out waiting for snapshot to become active”

Snapshot creation took longer than 10 minutes. This can happen with large Dockerfiles. Check the snapshot status in the Daytona dashboard — it may still be building. Subsequent runs will reuse the snapshot once it’s active.

​
Git clone fails for private repositories

See Private repositories above. You need a GitHub App configured and installed on the repository’s organization or account.

​
Stall watchdog kills the run

Long-running commands in Daytona sandboxes may trigger the 1800-second stall watchdog if they don’t produce events. For workflows with long-running operations, increase the stall_timeout in the workflow graph: 
digraph Example {
    graph [stall_timeout="1200"]
}