Runtimes

Where runs execute: local worktrees, cloud sandboxes, SSH hosts and your own infrastructure, and how the default runtime is chosen.

On this page

A runtime is where an agent’s commands actually run. Duun wraps CLI agent runtimes (Claude Code, Codex CLI, Gemini CLI, OpenCode) and starts them in an execution target: a worktree on your Mac, a cloud sandbox, a machine you reach over SSH, or infrastructure you connect. You manage execution targets in Settings → Runtimes.

Agent runtimes and execution targets

Two things are called “runtime” in Duun, and they combine:

LayerExamplesSet where
Agent runtime (the CLI)Claude Code, Codex CLI, Gemini CLI, OpenCodeOn each agent, in Runtime & model
Execution target (the machine)Local worktrees, E2B sandboxes, Modal, SSH hostSettings → Runtimes, per factory, or per agent

Any agent runtime can run on any execution target. The builder agent runs Claude Code whether its run lands in a local worktree or a cloud sandbox.

Built-in targets

TargetWhat it isGood for
Local worktreesParadev’s host-service and pty-daemon on your Mac. Agents work in real terminals, each run in its own git worktree.Fast iteration, repos that need local tools, zero compute cost
E2B sandboxesDisposable Linux sandboxes with a cached dependency snapshot.Parallel runs, untrusted work, Autonomous in sandbox
ModalGPU-capable sandboxes.Evals and jobs that need a GPU
SSH hostA machine you own, reached with a key Duun generates.Build boxes, staging servers, GPU hosts

Local worktrees are always available and can’t be disconnected. The number of slots (parallel runs on your Mac) is shown on the row, for example “Healthy · 4/8 in use”.

Add a runtime

Select Add runtime in Settings → Runtimes to connect one of these:

RuntimeDescription
ModalGPU-capable sandboxes
DaytonaDev environments from devcontainer.json
Fly MachinesFirecracker VMs near your users
KubernetesJobs in your own cluster

Each one asks for credentials, which are stored as workspace secrets in Settings → API keys & secrets. Select Test connection to check it; a healthy runtime reports its latency.

SSH hosts are managed as computers. Choose Manage in Computers on the SSH row, or see Computers and sandboxes.

The default runtime

One connected runtime is the workspace default, marked in the list. It is used when a factory doesn’t pick one. To change it, select another connected runtime or choose Make default from its menu.

The target for a run is resolved in this order:

  1. The step’s agent, if it has a fixed target (set in the agent’s Runtime & model step).
  2. The factory’s runtime setting.
  3. The workspace default.

You can’t disconnect the default runtime: pick another default first.

Isolation between runs

Whatever the target, every run gets its own working copy:

  • Local worktrees create a git worktree per run under ~/.paradev/worktrees/, on a branch named after the issue, so parallel runs never touch each other’s files.
  • Cloud sandboxes start from a snapshot of the repo with dependencies installed, and are destroyed or stopped when the run ends or sits idle.
  • SSH hosts run as an unprivileged user with a per-run config mounted for that run, never in your home folder.

Clean up old local worktrees in Settings → Storage & privacy → Clean up worktrees. Merged and closed branches are selected for you; active runs’ worktrees can’t be removed.

Runtime status

The status column comes from runtime hooks: each target reports health, slots in use and the runs attached. A target that stops reporting turns to an error state, and runs waiting for it stay queued instead of failing. Runs that were already working on it pause at their next step and show an ask in Inbox.

Disconnect a runtime

Choose Disconnect… from the runtime’s menu. Factories that pinned it fall back to the workspace default. Runs in progress on that target finish their current step first.

    Type to search the docs, help center and blog.