Skip to main content
A persistent sandbox is a reusable Linux microVM backed by a dedicated Archil disk. Stop and start it while retaining its disk, or pause and resume it to also preserve CPU and memory state. Use a persistent sandbox when you need a long-running environment. For an individual command on an existing disk, use disk.exec.
Persistent sandboxes are in preview and may be preempted. Preemption stops running processes and discards in-memory state, and recent filesystem changes may be lost.

Create and use a sandbox

Install the TypeScript SDK:
Create a sandbox from any public Linux OCI image, then run commands inside it. baseImage accepts Docker Hub shorthand such as python:3.13 or a full custom image reference such as ghcr.io/acme/agent-runtime:v2. Private registry images are not supported yet. If you need private image support or another sandbox feature, contact us.
Set maxTtlSeconds when creating the sandbox (60 to 28,800 seconds). For now, it cannot be changed after creation. Each start or resume gets that much powered-on time before Archil shuts down the VM while preserving its disk. The default is eight hours, and activity does not extend the timer.

Connect an interactive shell

Pass pty: true to stream terminal output and send input:

Expose an application

A sandbox can expose an application at a stable HTTPS URL. Archil starts or resumes an inactive sandbox when a request reaches the URL. Create a supervised process with the sandbox service manager:
The command returns the application’s hostname. Its process definition survives sandbox restarts.
Sandbox service hostnames are public. Add authentication before exposing private data or privileged actions.

Manage sandbox lifecycle

Pause preserves CPU and memory. Stop preserves the disk but cold-boots the next time you start:
Fork a sandbox to create an isolated, writable copy of its current environment:
The fork’s starting state depends on the source:
  • Running: Archil briefly pauses the source to capture its disk, CPU, and memory state, then resumes it.
  • Paused: The fork includes the source’s disk, CPU, and memory state.
  • Stopped: The fork includes the source’s disk state and cold-boots without memory state.
Forks can be forked again. Delete child forks before deleting their parent.

Reference