---
title: Railway Sandboxes
description: Isolated Linux VMs for coding agents and untrusted code. Create them in code, wire them into your project's private network, checkpoint, fork, and throw them away. Billed for what they use.
url: https://railway.com/sandboxes
---

# Railway Sandboxes

A Railway sandbox is an isolated, ephemeral Linux VM scoped to a Railway environment. You create it from the TypeScript SDK, the CLI, the dashboard, or the GraphQL API; run commands in it; read and write its files; and destroy it when you're done. It boots from a Debian base with git, Node, and common coding agents (Claude Code, Codex, OpenCode, Pi) preinstalled, and it can join your project's private network to reach your databases and services by hostname.

Sandboxes are available on every plan, including Free and the Trial.

- Docs: https://docs.railway.com/sandboxes
- CLI reference: https://docs.railway.com/cli/sandbox
- Guide, agents in sandboxes: https://docs.railway.com/guides/agents-in-sandboxes
- TypeScript SDK (open source): https://github.com/railwayapp/railway-ts-sdk

## Why a sandbox on Railway

- **Runs beside your real stack.** Create it with `networkIsolation: "PRIVATE"` and it joins the environment's private network. It reaches `postgres.railway.internal`, Redis, and internal services the same way your app does.
- **Pay for measured usage.** CPU bills for the seconds it's busy. Memory in use remains billable while an agent waits, along with any background CPU use or outbound traffic.
- **Prepare once, branch many.** Clone, install, and sign agents in once. Checkpoint the result, then boot or fork copies per attempt. Keep the one that works.

## Quick start

TypeScript SDK (`npm install railway`, Node.js 22+, reads `RAILWAY_API_TOKEN` and `RAILWAY_ENVIRONMENT_ID`):

```ts
import { Sandbox } from "railway";

const sandbox = await Sandbox.create({ networkIsolation: "PRIVATE" });

await sandbox.exec("git clone https://github.com/you/app /app");
await sandbox.exec("npm ci", { cwd: "/app" });
await sandbox.checkpoint("app-ready");

const fork = await sandbox.fork();
const { exitCode, stdout } = await fork.exec("npm test", { cwd: "/app" });

await Promise.all([sandbox.destroy(), fork.destroy()]);
```

CLI (inside a linked project; the CLI tracks the active sandbox, so no IDs):

```bash
railway sandbox create --private-network
railway sandbox exec -- git clone https://github.com/you/app /app
railway sandbox exec -- bash -lc 'cd /app && npm ci'
railway sandbox checkpoint create app-ready

railway sandbox create --checkpoint app-ready
railway sandbox exec -- bash -lc 'cd /app && claude -p "fix the failing test"'
railway sandbox destroy
```

Interactive: `railway sandbox ssh` opens a shell, `railway sandbox forward 3000` maps a sandbox port to localhost.

## The loop

```txt
create -> configure -> checkpoint -> create/fork -> verify -> destroy
```

1. **Create** a sandbox. Debian, git, Node, and coding agents are ready in seconds.
2. **Configure** it: clone the repo, install dependencies, seed variables, sign agents in.
3. **Checkpoint** the prepared disk under a name. It's stored server-side in the environment.
4. **Fork**: boot copies from the checkpoint, or fork a live sandbox per attempt.
5. **Verify**: run the agent, run the tests, stream output, forward a port or publish a domain.
6. **Destroy** the attempts. Or let the idle timeout do it.

## Capabilities

- `exec` with durable sessions: stream output live, detach, reattach from another process. Commands outlive the client.
- Files API: read, write, list, stat, mkdir, rename, remove. Streams for large files, automatic retries.
- Checkpoints: named disk snapshots stored in the environment. Boot from them by name.
- Forks: clone a running sandbox's filesystem into a new sandbox in one call.
- Templates: declare packages and build steps; Railway builds, content-hashes, and caches the image.
- Networking: `ISOLATED` (default, outbound internet only) or `PRIVATE` (joins the environment's private network).
- Public domains: up to 10 Railway-provided HTTPS domains per sandbox, one per port. Requires `PRIVATE`.
- SSH and port forwarding from the CLI, with keys on your Railway account.
- Regions: US West (default), US East, EU West, Southeast Asia. Choose a region for a new sandbox; forks stay in the source region.
- Idle timeout: enabled by default. Running commands and active sessions can keep a sandbox alive. Hobby and Pro can disable the timer.

## Pricing

Sandboxes bill at VM rates, metered per second, for what a sandbox consumes while it runs: CPU actually used, memory in use, and outbound traffic. Memory includes the operating system and filesystem cache. Idle sandboxes remain billable. Destroying a sandbox stops further compute usage.

| Resource | Rate | ≈ Per month, while running |
| --- | --- | --- |
| Memory | $0.00001929 per GB/s (in use) | $50 per GB |
| CPU | $0.00001929 per vCPU/s (active use) | $50 per vCPU |
| Egress | $0.05 per GB | — |

Monthly rates assume continuous use of one unit for a 30-day month. The examples below estimate compute charges from each workload's duration and average resource use:

| Scenario | Shape | Per run | At scale |
| --- | --- | --- | --- |
| Code review on every PR | Clone, install, run the agent. 8 minutes, 1 GB, 25% of a vCPU. | $0.01 per pull request | 1,000 PRs a month: $11.57 |
| Five agents on one bug | Fork a checkpoint five ways. Keep the winner. 30 minutes, 2 GB, 40% of a vCPU. | $0.08 per attempt | 5 attempts: $0.42 |
| Code execution in your product | An untrusted snippet runs, returns, and the sandbox is gone. 20 seconds, 500 MB, 1 vCPU. | $0.0006 per execution | 100,000 executions a month: $57.87 |
| A dev box for your day | SSH in with Claude Code and leave it attached all day. 480 minutes, 2 GB, 10% of a vCPU. | $1.17 per working day | 20 days a month: $23.33 |

Sandbox usage draws from the same included usage as the rest of your plan. Full rates: https://railway.com/pricing

## Limits by plan

| Plan | Running sandboxes per environment | Default size | Maximum size | Default idle timeout | Idle timeout range |
| --- | --- | --- | --- | --- | --- |
| Free Trial | 10 | 2 vCPU / 2 GB | 2 vCPU / 2 GB | 5 min | Up to 5 min |
| Free | 10 | 2 vCPU / 2 GB | 2 vCPU / 2 GB | 5 min | Up to 5 min |
| Hobby | 50 | 4 vCPU / 4 GB | 8 vCPU / 8 GB | 30 min | Up to 120 min, or never |
| Pro | 100 | 8 vCPU / 8 GB | 24 vCPU / 24 GB | 30 min | Up to 120 min, or never |
| Enterprise | Custom | 8 vCPU / 8 GB | Custom | 30 min | Up to 120 min, or never |

Size is the ceiling a sandbox can use; billing follows actual use. Request a size up to the maximum with the `resources` field on the `sandboxCreate` API mutation.

## Common questions

- **What is a Railway sandbox?** An isolated Linux VM you create through the TypeScript SDK, CLI, or dashboard. Git, Node.js, and coding agents are already installed, so you can start running commands and working with files right away.
- **How is a sandbox different from a service?** A service runs your deployed app, API, or worker. A sandbox gives your application a VM for a task, like running an agent or testing a change. Your code decides when to create it, what to save, and when to destroy it.
- **How much does a sandbox cost?** CPU and memory usage are billed per second, at $50/vCPU-month and $50/GB-month. Outbound traffic costs $0.05/GB. For example, a 20-minute task averaging 1 GB of memory and 30% of a vCPU costs about $0.03, plus outbound traffic.
- **Do I pay for an idle sandbox?** Yes. It still uses memory, and background work can use CPU and bandwidth. Sandboxes have an idle timeout by default, though running commands or active sessions can keep them alive. Destroy yours when you're done to stop compute charges.
- **Can a sandbox reach my database?** Yes. Set networking to PRIVATE and pass in your database credentials. Your sandbox can then connect to databases and services in the same environment. The default setting, ISOLATED, only allows outbound internet access.
- **What are checkpoints, forks, and templates?** A checkpoint saves a sandbox's disk so you can start from it later, even after deleting the original. A fork creates another sandbox from a running one's files. A template lets you reuse a setup, with builds cached for next time. Each new sandbox boots fresh; processes and memory aren't copied.
- **Which plans include sandboxes?** All of them, including Free and Trial. Your plan determines how many sandboxes you can run in each environment, their CPU and memory limits, and idle timeout options. Usage counts toward your plan's included credit.
- **Can my sandbox have a public URL?** Yes. Choose PRIVATE networking and request a domain when you create it. You can have up to 10 domains, each pointing to a different port. They're removed when you destroy the sandbox.

## Related

- Pricing: https://railway.com/pricing
- Agents on Railway: https://railway.com/agents
- Railway MCP server: https://railway.com/mcp
- Docs: https://docs.railway.com/sandboxes

## Open this page

<https://railway.com/sandboxes> — [Open in browser](https://railway.com/sandboxes)