|Docs

Use Agents in Railway Sandboxes

agentssandboxesclaudecli

A sandbox is a short-lived, isolated Linux environment you provision on demand, run commands in, and destroy. This guide covers how to fold sandboxes into your development loop and let agents do real work inside them.

Two layers of agents come together here. Your local agent, like Claude Code or Codex running on your laptop, drives sandboxes through the Railway CLI or the TypeScript SDK. Inside the sandbox, the same agent harnesses ship in the default image, so the environment can run untrusted code, test against your real infrastructure, and do the work without you bootstrapping a toolchain each time.

The guide builds toward a concrete example: the Repo Review Agent, an app that prepares a repository once, then fans out one sandbox per agent to review it for bugs, architecture, security, and product polish. By the end, you'll understand where each sandbox primitive fits in that flow.

Why sandboxes for development

A sandbox isn't a shell floating off to the side. Because it lives in a Railway environment, it can join the same private network as the rest of your services. That changes what an agent can do inside one.

  • Isolation for untrusted work. Run agent-generated code, dependency installs, and migrations in a throwaway environment instead of on your machine.
  • Access to real infrastructure. Create a sandbox on the private network and it can reach the Postgres, Redis, and internal services already in your project, so agents test against the same infrastructure they'll ship against.
  • A branchable workspace. Snapshot expensive setup once, then boot or fork as many copies as you need. Each new run is one command, not a fresh bootstrap.

The development loop

The loop most teams adopt with sandboxes looks like this:

Each step maps to a sandbox primitive:

  1. Create: start a sandbox. The default image already ships git, Node, npm, and the agent harnesses, so most work needs no setup image.
  2. Configure: clone a repo, install dependencies, sign agents in, write guidance files, seed variables.
  3. Checkpoint: snapshot the prepared state into a named, server-side snapshot.
  4. Create or fork: boot fresh sandboxes from the checkpoint, or fork a running one when the work branches.
  5. Verify: run the agent, run tests, inspect the result.
  6. Destroy: tear down the temporary sandboxes and reclaim the resources.

The point of the loop is that an agent doesn't rebuild the world every time. It carries forward the useful state and throws away the rest.

Prerequisites

Drive sandboxes from the CLI

For most development work, you don't need to write code around a sandbox. The CLI gives you the full loop from your terminal, and the railway sandbox reference covers every subcommand. Your local agent can run these same commands once you install Railway Agent Skills with railway setup agent, which teaches Claude Code, Codex, OpenCode, and Cursor how to drive Railway.

Sign agents in once and checkpoint the result

The agent harnesses are in the image, but each one still needs credentials. Sign them in once, then capture a checkpoint so every later sandbox boots already authenticated. This is the one-time configuration the Repo Review Agent depends on.

Create a sandbox and open a shell in it:

Inside the sandbox, sign in to each agent you plan to use:

claude, codex, and opencode each persist credentials to disk, so they survive a checkpoint. Pi has no interactive login and reads its key from ANTHROPIC_API_KEY at runtime, so you pass that key in at create time instead.

Exit the shell and capture the authenticated state under a name you'll reuse:

The checkpoint is stored server-side in the environment, so you can destroy the original sandbox and still boot from agent-box from any machine.

Run the loop

Create a sandbox on the private network so it can reach your other services. The default image already has the toolchain, so there's nothing to pre-install:

Clone a repo and install dependencies. The CLI keeps an active sandbox for the session, so these commands need no ID. Run non-interactive commands through bash -lc to get the sandbox's configured mise toolchain:

Checkpoint the prepared workspace so you can return to it without repeating the clone and install:

Boot a fresh sandbox from that checkpoint and run an agent against the code:

To watch a dev server the sandbox is running, start it in the background with --detach, then forward the port back to your machine. The Repo Review Agent binds PORT=8080, so forward 8080:

When the work branches, fork the active sandbox to try a second approach without disturbing the first, then destroy what you no longer need:

A short idle timeout also tears a sandbox down automatically if you forget.

Build the flow into an app with the SDK

When you want sandboxes inside an application instead of your terminal, the TypeScript SDK is the programmatic interface. It's open source on GitHub. Install it with bun add railway, or scaffold a new project with bun create railway@latest.

The minimal shape creates a sandbox, runs a command, and destroys it:

Sandbox.create() reads RAILWAY_API_TOKEN and RAILWAY_ENVIRONMENT_ID from the environment and resolves once the sandbox is running and ready to accept commands.

The Repo Review Agent builds the full loop on top of that. Its flow, defined in src/lib/review.server.ts, runs end to end on each review:

The sections below walk through that pipeline.

Share one set of sandbox options

Every sandbox in the app is created with the same token, environment, idle timeout, and the provider keys the harnesses read at runtime. The app centralizes them so each create call is consistent:

env bakes variables into the sandbox for its whole lifetime, available to every command. Values can reference other Railway variables, for example ${{Postgres.DATABASE_URL}}, resolved when the sandbox is created. Pair an internal reference with networkIsolation: "PRIVATE" so the sandbox can resolve it over the private network.

Prepare the repository once, then checkpoint it

Boot the base sandbox from the agent-box checkpoint you captured with the CLI, clone the target repo, install dependencies, and run a build to verify the workspace is sound. Then checkpoint the prepared state under a fresh name:

exec doesn't throw on a non-zero exit code, so the app inspects exitCode and timedOut after each step. The base.files.write call writes an AGENTS.md guidance file straight into the workspace, so an agent running inside knows how to behave. The checkpoint captures the cloned, installed, verified workspace, so every agent run skips that setup.

Fan out one sandbox per agent

With the prepared checkpoint in hand, the app creates one sandbox per agent and runs each harness in headless mode against the same starting state. Because every sandbox boots from the same checkpoint, the reviews are isolated and run in parallel:

Each harness runs with the flags that make it non-interactive: --print and --permission-mode dontAsk for Claude Code, codex exec with approvals bypassed, opencode run, and pi --print --approve. The --json and --format json flags give the app structured output it can parse into a summary per agent. quote shell-escapes the prompt so it travels safely inside the bash -lc string. Wrapping every sandbox run in try/finally guarantees the sandbox is destroyed even when a review throws.

Clean up the base and the checkpoint

When all reviews finish, destroy the base sandbox and delete the temporary checkpoint so neither counts against your environment's sandbox limit:

The reusable agent-box checkpoint stays in place. The next review boots from it again, so the only per-run cost is the clone, install, and the agent work itself.

Keep a long-lived agent running after you disconnect

A command started with exec runs on the sandbox independently of the client that started it, so an agent keeps working even if your process disconnects. Start the agent, grab its durable sessionName, and detach:

Long-running commands keep going in the sandbox after you detach. Reattach later from any process by passing the session name back to exec:

You aren't forced to keep one local process alive to keep the work going. The sandbox is where the work happens, and getting back into that state is one call away.

Fork instead of recreating when the work branches

The app creates a new sandbox per agent from the checkpoint, but forking is an option when you're branching from a sandbox that's already running. A fork clones a running sandbox's filesystem into a new, independent one: files are preserved, running processes are not. Install dependencies once, then fork per task:

A fork copies the workbench, not the half-running experiment, which is usually what you want when you split one prepared workspace into parallel attempts.

Agents bundled in the default image

The default sandbox image includes Claude Code, Codex, OpenCode, and Pi. You don't spend the first minutes of every session reinstalling a harness you've set up many times before.

For now, you pass each agent its configuration or API key. There are two ways to get credentials into a sandbox:

  • Sign in and checkpoint for harnesses that persist credentials to disk, like claude auth login. The authenticated state survives the checkpoint, as shown in the CLI setup above.
  • Pass a key at create time for harnesses that read from the environment, like Pi reading ANTHROPIC_API_KEY. Use --variable in the CLI or the env option in the SDK:

Templates, checkpoints, and forks

The three primitives look similar but serve different points in the loop.

PrimitiveWhat it capturesWhen to use it
TemplateAn ordered list of build steps, content-addressed and cachedA repeatable base for tooling the default image doesn't include
CheckpointThe disk of a running sandbox as a named, server-side snapshotAfter expensive live setup: signed-in agents, cloned repo, installed dependencies
ForkA clone of a running sandbox into another running sandboxWhen the work branches right now: parallel agent attempts from one prepared workspace

A template is built from instructions and rebuilds cheaply, but the Repo Review Agent skips it because git, Node, npm, and the agents already ship in the image. A checkpoint outlives its source sandbox, so you can destroy the original and still create from it later. A fork needs a running source and copies its disk, not its processes.

Next steps

Explore these resources to go deeper on sandboxes and agents: