Fork

Duplicate a running or paused sandbox — memory and filesystem — into a new independent sandbox.

Fork duplicates a sandbox — its guest RAM and its filesystem, captured at a single instant — into a brand-new sandbox with its own id. The fork is a perfect copy of the source at the moment of the fork: same processes, same memory, same files. From that instant on, the two sandboxes are fully independent and diverge freely.

This unlocks patterns that are awkward or impossible with a single environment: branching an agent's state to explore several strategies in parallel, stamping out copies of an expensively warmed-up environment, or splitting a live system into "keep going" and "poke at the bug" halves. Fork requires a persistent source sandbox (persistent: true — see Persistent Sandboxes).

Forking a running sandbox

POST /vms/:id/fork on a running source briefly freezes it internally to get a consistent capture — a window of seconds, proportional to the sandbox's RAM size — then lets the source continue running. The fork automatically resumes and comes up running, with its processes continuing from the fork instant.

Forking a paused sandbox

Forking a paused source involves no freeze at all, since its state is already captured. The fork is created paused, just like its source. You then choose how to bring it up:

resume() — continue its processes and memory from the fork point, or
start() — discard the captured memory and cold-boot its filesystem.

Pausing once and forking repeatedly is the cheapest way to stamp out many copies of the same state.

Independence and lineage

Fork and source share nothing after the fork completes: separate storage, separate compute, and a fresh network identity for the fork (new IP; declared ports get their own mappings). The fork records its origin in a forked_from field so you can trace lineage, and it inherits the source's spot tier — a fork of a spot sandbox is itself spot.

Restrictions in v1

Fork has the same v1 refusals as pause: the API returns 409 Conflict (a not-supported error in the SDKs) when the source is not persistent, has attached volumes, or has a Docker data device.

Examples

Fork a warmed-up sandbox into a copy and run both independently:

Python

from rlp import CreateSandboxFromImageParams, Daytona
 
daytona = Daytona()
source = daytona.create(CreateSandboxFromImageParams(
    image="python:3.12-slim",
    persistent=True,
))
 
# Warm the source up: install dependencies, load data, start services...
source.process.exec("pip install numpy pandas")
 
# Duplicate it. The source keeps running; the fork is a new sandbox.
fork = source.fork(name="experiment-b")
fork.wait_until_started()
 
# The two are now fully independent.
fork.process.exec("python run_experiment.py --variant b")
source.process.exec("python run_experiment.py --variant a")

TypeScript

import { Daytona } from '@rlp/sdk'
 
const daytona = new Daytona()
const source = await daytona.create({
  image: 'python:3.12-slim',
  persistent: true,
})
 
// Warm the source up.
await source.process.executeCommand('pip install numpy pandas')
 
// Duplicate it. The source keeps running; the fork is a new sandbox.
const fork = await source.fork('experiment-b')
await fork.waitUntilStarted()
 
// The two are now fully independent.
await fork.process.executeCommand('python run_experiment.py --variant b')
await source.process.executeCommand('python run_experiment.py --variant a')

cURL

# Fork; the response carries the new sandbox's id.
curl -X POST https://api.rl.trydaytona.com/vms/$SANDBOX_ID/fork \
  -H "Authorization: Bearer $RLP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "experiment-b"}'
 
# Inspect the fork (note the forked_from lineage field).
curl https://api.rl.trydaytona.com/vms/$FORK_ID \
  -H "Authorization: Bearer $RLP_API_KEY"

Note: the name in the fork request is optional; omit the body entirely to get an auto-named fork.

Typical use cases

Agent tree search — pause an agent at a decision point, fork one copy per branch, and let each explore independently.
Templating a warm environment — build and warm one sandbox, pause it, then fork it for each new task instead of re-installing from scratch.
A/B debugging — fork a misbehaving live sandbox; debug the fork aggressively while the source keeps serving.