Depot Sandboxes | Depot Sandboxes | Depot Docs
Depot Sandboxes
Depot Sandboxes give you isolated Linux microVMs for running code, tests, and agents on x86-64 or ARM64. Each sandbox provides a full Linux environment where you can install dependencies, run commands, and use Docker. Depot manages the underlying compute, so you don't need to operate a fleet of machines.
Sandboxes run on Depot Metal, the compute and storage platform that powers Depot CI. Use the Sandbox SDK to create and control sandboxes from your own code.
Get started with the Sandbox SDK
The @depot/sandbox package provides a Node.js SDK for creating sandboxes, running commands, and working with files. It requires Node.js 20 or newer.
Follow the SDK quickstart to create a sandbox, run a command, write a file, and stop the sandbox. The reference also covers authentication, resource configuration, and timeouts.
Feature summary
| Feature | What you can do |
|---|---|
| Isolated Linux environments | Run workloads in microVMs with a full Linux system call interface, including support for Docker. |
| Configurable resources | Choose x86-64 or ARM64 architecture, CPU, memory, and disk resources when you create a sandbox. |
| Command execution | Run commands, stream their output, and inspect their exit codes from your application. |
| File system access | Read and write files, create directories, and inspect file metadata through an interface modeled on node:fs/promises. |
| Lifecycle control | Create, get, list, stop, and kill sandboxes. Set timeouts to control how long environments remain available. |
| Custom images | Start with Depot's default base image or specify an image with the tools and dependencies your workload needs. |
Use secrets, private networking, and build caches
Sandboxes integrate with the Depot services your workloads already use:
- Depot CI secrets: Select organization-wide secrets and expose them to commands as environment variables. Organization Members can use organization-wide secrets; selecting repository- or environment-scoped secrets requires Owner access.
- Tailscale: Sandboxes automatically join your organization's tailnet when the integration is configured and enabled for sandboxes, giving commands access to private services.
- Depot Cache: Supported build tools receive cache credentials and configuration automatically. Depot Cache is enabled by default.
The SDK lets you disable Tailscale or automatic cache configuration for an individual sandbox.
Save files and resume work
Use sandbox.snapshot() to save files from a running sandbox, then pass the snapshot to Sandbox.create(client, {snapshot}) to restore them into a new sandbox. The new sandbox uses the snapshot's runtime and architecture by default.
Snapshots preserve files from the sandbox user's home directory and writable /workspace directory, not running processes or memory. Sandboxes with repository- or environment-scoped secrets cannot be snapshotted. Managed Agents handles workspace snapshots automatically; the SDK gives you control over when to save and restore files.
You can't restart a stopped sandbox. Take a snapshot before stopping if you need to restore its files into a new sandbox later.
How Depot Sandboxes work
Your application requests a sandbox through the SDK. Depot provisions a microVM with the requested resources and starts its Linux environment. You can then run commands and modify files remotely. Stop the sandbox when your work finishes, or let its configured timeout end the run.
Sandbox lifecycle, compute, and storage Your application requests a sandbox through the SDK. Depot manages its resources and lifetime and starts a Linux microVM on a bare-metal compute host. The microVM runs your commands and tools. Dedicated storage servers provide its disk over NVMe-oF/TCP, cache disk blocks on NVMe SSDs, and read and write base images and snapshots in S3. Your application Sandbox SDK Sandbox management Resources, startup, and lifetime Create sandbox Starts microVM Depot Metal Bare-metal compute host Depot sandbox Linux microVM Commands, tools, and Docker MicroVM hypervisor In-memory disk cache Storage servers NVMe SSDs cache disk blocks In-memory disk cache S3 Base images and snapshots Durable disk block storage Disk reads / writes NVMe-oF/TCP Disk blocks
Depot Metal separates compute from storage. MicroVMs run on bare-metal compute hosts, while dedicated storage servers provide their disks from NVMe-backed storage. Depot Metal uses S3 to store base images and snapshots, and caches disk blocks close to the compute. You don't need to configure these infrastructure components to use a sandbox.
Depot on Depot Sandboxes
Sandboxes also provide the execution environments for Depot products:
- Depot CI: Workflow jobs run in sandboxes with the tools needed to execute GitHub Actions workflows. Depot CI handles job scheduling, logs, and workflow orchestration. See the Depot CI overview.
- Managed agents: Depot provisions sandboxes to run coding agents through connected providers. Managed agents handles provider setup and workspace snapshots so sessions can continue across sandbox runs.
Use the Sandbox SDK when you want to control the environment and execution directly, such as giving each task a separate test environment or building your own agent runner.
Products that use Depot Sandboxes Depot CI runs workflow jobs, Managed agents runs coding agents, and your application uses the Sandbox SDK. Each workload runs in an isolated Linux microVM on Depot Metal, with bare-metal compute and NVMe-backed storage. Depot CI Workflow jobs Depot sandbox Linux microVM Builds and tests Managed agents Coding agent sessions Depot sandbox Linux microVM Agent commands and tools Your application Sandbox SDK Depot sandbox Linux microVM Your code and processes Depot Metal Bare-metal compute · NVMe-backed storage · Base images and snapshots in S3
Pricing
Depot Sandboxes, Managed Agents, and Depot CI share one pool of included sandbox minutes. There's no separate allowance for each product. Compute is tracked and billed by the second, with no one-minute minimum per run.
Included minutes are measured at 2 vCPUs. Larger sandboxes consume the pool proportionally faster. For example, a 4-vCPU sandbox uses 2 included minutes for every minute it runs.
| Developer plan | Startup plan | Business plan | |
|---|---|---|---|
| Plan cost | $20/month | $200/month | Custom |
| Shared sandbox minutes | 2,000/month | 20,000/month | Custom |
| Additional compute | $0.00005/vCPU-second | $0.00005/vCPU-second | Custom |
| Cache and registry storage | 25 GB included + $0.20/GB/month after |
250 GB included + $0.20/GB/month after |
Custom |
The included minutes aren't a hard cap. Additional usage is billed automatically at $0.00005 per vCPU-second on Developer and Startup. A 2-vCPU sandbox costs $0.0001 per second after the shared allowance is used.