Skip to main content
When an agent runs a shell command, edits a file, or searches code, it does so inside a sandbox. The sandbox is the execution environment for all tool operations — it controls where commands run, which files are visible, and how much isolation exists between the agent and the host. Fabro supports three sandbox providers. Each one implements the same interface (file I/O, command execution, grep, glob), so workflows run identically regardless of which provider you choose. The difference is in where and how the tools execute.
ProviderRuns onUse caseStatus
localHost machineDevelopment, trusted workflowsAvailable
dockerDocker containerReproducible environments, untrusted codeAvailable
daytonaCloud VMCI/CD, team-shared runs, SSH debuggingAvailable

​
Choosing a provider

Set the sandbox provider via CLI flag, run config TOML, or server defaults: 
# CLI flag
fabro run workflow.fabro --sandbox local
fabro run workflow.fabro --sandbox docker
fabro run workflow.fabro --sandbox daytona
run.toml
# Run config TOML
[run.sandbox]
provider = "daytona"
The precedence order is: CLI flag > run config TOML > server defaults > built-in default (local).

​
Local

The local sandbox runs all tool operations directly on the host machine. It’s the default and the simplest option — no setup required beyond the Fabro binary itself.

​
How it works

  • Working directory — Set to the current directory (or directory from the run config). Fabro creates it if it doesn’t exist.
  • Commands — Executed via /bin/bash -c in the working directory.
  • File operations — Read and write directly to the host filesystem. Relative paths resolve against the working directory.
  • Cleanup — No-op. Local sandbox doesn’t create or destroy anything on cleanup.

​
Environment variable filtering

The local sandbox filters sensitive environment variables before passing them to commands. Variables ending in _API_KEY, _SECRET, _TOKEN, _PASSWORD, or _CREDENTIAL are stripped. A safelist of common variables (PATH, HOME, USER, SHELL, LANG, TERM, TMPDIR, GOPATH, CARGO_HOME, NVM_DIR) is always passed through.
The local sandbox offers no isolation. Agents can read and modify any file on the host. Use docker or daytona when running untrusted workflows or when you need a reproducible environment.

​
Docker

The Docker sandbox runs all tool operations inside a Docker container. The host working directory is bind-mounted into the container, so file changes are visible on both sides.

​
Prerequisites

  • Docker Engine running on the host
  • The configured image available locally (or auto_pull enabled)

​
How it works

  • Container lifecycle — On initialize(), Fabro pulls the image (if needed), creates a container with sleep infinity, and starts it. On cleanup(), Fabro stops and removes the container.
  • Working directory — The host working directory is bind-mounted at /workspace inside the container. All relative paths resolve against this mount point.
  • Commands — Executed via docker exec with /bin/bash -c inside the container. Timeout and cancellation are supported.
  • File writes — Use the Docker API’s tar upload to avoid shell escaping issues with special characters.
  • Platform detection — The container’s uname -r is cached at startup.

​
Configuration

The Docker sandbox is configured through the DockerSandboxConfig:
SettingDefaultDescription
imagefabro-agent:latestDocker image to use
container_mount_point/workspaceMount point inside the container
network_modebridgeDocker network mode
extra_mounts[]Additional host:container bind mounts
memory_limitunlimitedMemory limit in bytes
cpu_quotaunlimitedCPU quota (microseconds per 100ms period)
auto_pulltruePull the image if not found locally
env_vars[]Additional KEY=VALUE environment variables

​
Preserving the container

By default, the container is destroyed when the run finishes. To keep it alive for debugging: 
fabro run workflow.fabro --sandbox docker --preserve-sandbox
Or in the run config:
run.toml
[run.sandbox]
provider = "docker"
preserve = true
When preserved, Fabro prints the container ID so you can reconnect with docker exec -it <id> bash.

​
Daytona

The Daytona sandbox runs all tool operations inside a cloud-hosted VM managed by Daytona. It provides full machine-level isolation, automatic git cloning, and SSH access for debugging.

​
Prerequisites

  • A DAYTONA_API_KEY environment variable
  • A GitHub App configured via fabro install (for private repository cloning)

​
How it works

  • Sandbox lifecycle — On initialize(), Fabro creates a Daytona sandbox (from an image or a snapshot), clones the current git repository into it, and waits until it’s ready. On cleanup(), the sandbox is deleted.
  • Working directory — Fixed at /home/daytona/workspace. The current repository is cloned there automatically.
  • Git clone — Fabro detects the local origin remote URL and current branch, converts SSH URLs to HTTPS, and clones into the sandbox. For private repositories, Fabro uses a GitHub App Installation Access Token scoped to contents: read on the specific repository. Public repositories are cloned without credentials. If no git repo is detected, the working directory is created empty.
  • Commands — Executed via the Daytona process API. Commands are base64-encoded and piped through sh to support pipes, environment variables, and other shell features.
  • Ephemeral — Sandboxes are created with ephemeral: true and a unique timestamped name (e.g. fabro-20260305-142301-a3f2).

​
Snapshots

Snapshots let you pre-build an environment image so each run starts with dependencies already installed. If the named snapshot doesn’t exist and a dockerfile is provided, Fabro creates it automatically and polls until it’s ready (up to 10 minutes).
run.toml
[run.sandbox]
provider = "daytona"

[run.sandbox.daytona]
auto_stop_interval = 60

[run.sandbox.daytona.snapshot]
name = "rust-dev"
cpu = 4
memory = "8GB"
disk = "20GB"
dockerfile = "FROM rust:1.85-slim-bookworm\nRUN apt-get update && apt-get install -y git ripgrep"
FieldDescription
nameSnapshot identifier. Reused across runs if it already exists.
cpuCPU cores for the snapshot VM.
memoryMemory in GB.
diskDisk in GB.
dockerfileDockerfile content for building the snapshot. Required when creating a new snapshot.
If the snapshot already exists and is in Active state, Fabro uses it directly. If it’s in Building or Pending state, Fabro polls with exponential backoff until it’s ready.

​
Labels

Attach key-value labels to sandboxes for filtering and identification in the Daytona dashboard:
run.toml
[run.sandbox.daytona.labels]
project = "fabro"
env = "ci"
team = "platform"
When using server defaults, labels are merged — run config labels override default labels on key collisions.

​
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.

​
Preserving the sandbox

Like Docker, Daytona sandboxes are destroyed on cleanup by default. Use --preserve-sandbox to keep them alive: 
fabro run workflow.fabro --sandbox daytona --preserve-sandbox
Fabro prints the sandbox name so you can find it in the Daytona dashboard.

​
Auto-stop

The auto_stop_interval setting (in minutes) tells Daytona to stop the sandbox after a period of inactivity. This saves costs for long-running sandboxes that may sit idle:
run.toml
[run.sandbox.daytona]
auto_stop_interval = 30

​
Sandboxing

Sandboxes isolate agent execution from the host machine. When an agent runs a shell command, edits a file, or searches code, it does so inside a sandbox — preventing unintended side effects and providing a reproducible environment for each run.

​
Filesystem

Each provider offers a different level of filesystem isolation:
ProviderIsolationWhat agents can access
localNoneThe entire host filesystem. Agents can read and modify any file.
dockerContainer-levelOnly the bind-mounted working directory (/workspace by default) and whatever is in the container image. Host files outside the mount are inaccessible.
daytonaFull machineA cloud VM with the repository cloned into /home/daytona/workspace. The host filesystem is completely inaccessible.
For local, Fabro filters sensitive environment variables (those ending in _API_KEY, _SECRET, _TOKEN, _PASSWORD, or _CREDENTIAL) but does not restrict file access. Use docker or daytona when running untrusted workflows.

​
Network

Each provider handles outbound network access differently:
ProviderDefaultControls
localFull accessNo network isolation. Agents have the same network access as the host.
dockerBridge networkSet via the network_mode config option. Supports all Docker network modes (bridge, none, host, etc.).
daytonaFull accessConfigurable via the network setting with three modes: "allow_all", "block", or CIDR-based allow lists.
For Daytona, network access is configured in the [run.sandbox.daytona] section:
run.toml
# Block all egress
[run.sandbox.daytona]
network = "block"

# Allow only specific CIDRs
[run.sandbox.daytona]
network = { allow_list = ["208.80.154.232/32", "10.0.0.0/8"] }
When using server defaults, the run config network overrides the server default. If neither specifies network, Daytona’s own default (full access) applies.

​
Safety guardrails

Regardless of which provider you use, Fabro applies a read-before-write guardrail. Agents must read a file (via read_file or grep) before they can modify it with write_file or delete_file. Writing to new files that don’t yet exist is always allowed. This prevents agents from blindly overwriting files they haven’t inspected.