---
title: Sandboxes and desktop
description: The isolated Linux workstation a run executes in, the provider behind it, warm pools, the visible desktop, and how a run survives a backend restart.
sidebar:
  order: 5
---

Work runs inside an isolated sandbox, not in the backend process. The backend
drives the sandbox from outside and records everything it observes.

## Sandbox

The isolated Linux workstation where agent commands, repositories, browser
automation, desktop apps, and recordings run. A thread gets one sandbox and one
working directory, retained and reused across its runs: the lease checks
liveness and required labels before reuse and re-provisions when the retained
sandbox is stale (`backend/src/engines/thread-sandbox.ts`). A run executes
inside its thread's sandbox.

## Sandbox provider

A vendor-specific implementation selected behind a provider-neutral sandbox
contract. **Daytona** and **Cube** expose the same required process, filesystem,
PTY, preview, and lifecycle boundary, then keep provider-specific behavior and
tests for native capabilities. Code above the contract does not branch on the
provider.

## Warm pool

Prepared sandboxes kept ready so a new run avoids most cold-start work. Warm-pool
claimable creation and parallelized post-sandbox preparation are part of the
turn-start latency effort.

## Desktop

The visible XFCE and Chromium workstation shown through noVNC. Readiness is
strict: it requires the noVNC page, RFB, XFCE, browser CDP, and both CDP relays.
Daytona can drive the desktop natively, while Cube uses trusted X11 controls. An
engine controls it through the desktop computer-use tools, and desktop recording
publishes a real MP4 artifact.

## Restart reconciliation

Because the sandbox runs independently of the backend, a backend restart does not
kill a live run:

1. **The sandbox keeps executing**

    The engine process inside the sandbox is unaffected by a backend bounce.

2. **A recovery loop re-probes**

    On restart, a background loop finds the in-flight session and streams the
    interim provider events into the timeline with a visible heartbeat.

3. **The real result is adopted**

    The recovered run adopts the finished result, or fails honestly at a bounded
    deadline, rather than discarding work that actually completed.

<div style={{ background: "#ffffff", border: "1px solid #ebebeb", borderRadius: "12px", padding: "16px", margin: "1.5rem 0" }}>
  <img
    src="/docs/diagrams/run-survives-backend-restart.svg"
    alt="Two lanes over time: the sandbox keeps executing through a backend crash while boot recovery and the adaptive reconcile loop adopt the finished result"
    style={{ width: "100%", height: "auto", display: "block" }}
  />
  <p style={{ margin: "12px 4px 0", fontSize: "13px", color: "var(--blume-muted-foreground)" }}>
    The sandbox lane never stops: the one-shot boot pass (runs/recovery.ts:41-58)
    settles the commands mailbox, then the adaptive loop (recovery.ts:288,
    index.ts:348) re-probes every 15s with run.reconciling heartbeats until it
    adopts the real result or fails honestly at the bounded deadline.
  </p>
</div>

:::warning
The sandbox provider interface does not expose explicit pause, checkpoint, or
snapshot operations yet. Recovery re-probes and adopts; it does not resume from a
saved snapshot.
:::