railway sandbox

Create, connect to, run commands in, forward ports into, and destroy ephemeral sandboxes in a Railway environment.

Usage

Aliases

• railway sandboxes
• railway sbx

Subcommands

Active sandbox

create and fork set the new sandbox as the active sandbox. The ssh, exec, forward, fork, checkpoint create, and destroy commands act on the active sandbox when you don't pass an ID, so a typical session needs no IDs at all. Running ssh or exec against a specific sandbox makes that one active.

Pass --id <ID> (or a positional ID for fork and destroy) to target a specific sandbox instead. list marks the active sandbox with an asterisk.

Examples

Create a sandbox

Create a sandbox with an idle timeout

Railway auto-destroys the sandbox after it sits idle for the given number of minutes. The default and allowed range depend on your plan, so see Idle timeout for the per-plan values.

Create a sandbox on the private network

The sandbox joins the environment's private network and can reach your other services. See Private networking.

Fork a sandbox

This forks the active sandbox. The new sandbox becomes active, so a following ssh or exec targets the fork. Pass an ID to fork a specific sandbox.

List sandboxes

Connect to the active sandbox

Connect to a specific sandbox

Run a command over SSH instead of opening a shell

Run a command

exec streams the command's output live and exits with the command's exit code. Piped stdin is forwarded, so input redirection works too.

Run a command in a specific sandbox with a timeout

--timeout sets a client-side deadline in seconds. When it expires, the command receives SIGTERM and exec exits with code 124. Without it, the command runs until it exits.

Run a command in the background

--detach starts the command, prints its durable session name to stdout, and returns immediately. The command keeps running in the sandbox.

Reattach to a running command

This reattaches to a command started with --detach or one that disconnected mid-run. The CLI replays the output retained for the session, then follows it live. Pass --resume-from-last-read to receive only the output produced since the server's last read instead of replaying.

Forward a port into the active sandbox

This maps localhost:3000 to port 3000 inside the sandbox, so a server running in the sandbox is reachable from your machine. If the local port is already in use, the CLI picks a nearby free port unless you pass --strict.

Forward to a different local port

In LOCAL:REMOTE form, localhost:8080 maps to port 3000 in the sandbox.

Forward several ports at once

All requested ports are forwarded over a single connection. Forwarding runs in the foreground and stays open until you stop it with Ctrl+C.

Destroy the active sandbox

Destroy a specific sandbox

Options for

Options for

The source sandbox must be running. The fork clones its filesystem into a new sandbox in the same environment and boots fresh, so files are preserved but running processes are not.

Options for

Options for

Connecting over SSH requires an SSH key on your Railway account. See railway ssh for key setup, and add keys at Account Settings -> SSH Keys.

Options for

Options for

Options for

Forwarding runs over SSH, so it needs an SSH key on your Railway account, the same as ssh. It stays in the foreground until you stop it with Ctrl+C, and while it's up, a heartbeat keeps the sandbox from being destroyed as idle.

Templates

A template is a pre-built filesystem snapshot you can boot sandboxes from, which saves setup time. You build one from an ordered list of shell instructions. Railway content-addresses each template by the hash of its instructions and caches the snapshot for about 7 days, so rebuilding an identical template is an instant cache hit.

The CLI stores the templates it builds locally, so you can reference one by a name you assign with --name or by its template ID.

Build a template

Pass -c once per build step. Steps run in order, and each must exit 0 within 10 minutes. The --wait flag polls until the build reports READY or FAILED.

Create a sandbox from a template

Reference the template by the local name you gave it or by its template ID.

Options for

template status <ID_OR_NAME> and template list each accept --json.

Checkpoints

A checkpoint is a named snapshot of a sandbox's disk, captured from a running sandbox. Capture one after expensive setup, then boot new sandboxes from it instead of repeating the setup. Where a template is built from a list of shell instructions and tracked in the CLI's local store, a checkpoint captures the live disk of an existing sandbox and is stored server-side in the environment, so it works from any machine.

Capture a checkpoint

This captures the active sandbox. Pass --id to capture a specific one. The sandbox must be running, and it keeps running during the capture.

Capture is synchronous, so the checkpoint is bootable as soon as the command returns. A sandbox with a lot of changed disk takes longer to capture. Reusing a name replaces that checkpoint with the new capture.

Create a sandbox from a checkpoint

The new sandbox boots fresh from a copy of the checkpointed disk, so files are preserved but running processes are not. You can destroy the source sandbox after capturing and still create from the checkpoint later.

List, rename, and delete checkpoints

Renaming fails if a checkpoint with the new name already exists. After a rename, create --checkpoint works with the new name only. Deleting a checkpoint also deletes its underlying disk snapshot.

Options for

checkpoint list and checkpoint rename each accept --json. checkpoint rename takes the current name and the new name as positional arguments, and checkpoint delete takes the name to delete.

Checkpoint limits

The number of checkpoints an environment can hold matches its plan's sandbox limit, listed in Sandbox limits. Checkpoints are counted separately from running sandboxes, and replacing a checkpoint by reusing its name doesn't increase the count.

Variables

create and fork can seed environment variables into a sandbox. They're available to every command, over both exec and SSH.

Set variables inline with --variable. The flag is repeatable and comma-separable.

A comma splits the value only when every segment is its own KEY=VALUE pair, so values that contain commas stay intact.

Load variables from a .env file with --env-file, which is also repeatable. When the same key is set in both places, --variable flags take precedence.

Values can reference other Railway variables, resolved server-side when the sandbox is created. Use the bare Service.VARIABLE form or the full ${{Service.VARIABLE}} form.

Resolving a reference to a service's internal address requires the private network, so pair internal-URL references with --private-network.

Private networking

By default a sandbox is isolated: it has outbound internet access but can't reach other services in your environment over private networking. Pass --private-network to create or fork to place the sandbox on the environment's private network, so it can reach services like postgres.railway.internal and they can reach it. See Networking for the full description of both modes.

Common options

These flags apply to every subcommand.

Without these flags, the CLI uses your linked project and environment. In an interactive shell with no link, the CLI prompts you to select a workspace, project, and environment. In a non-interactive shell with no link, pass both --project and --environment, or run railway link first.

Related

• Sandboxes
• railway ssh
• railway link