Sandbox

Source: src/Railway/Sandbox.ts

A Railway.Sandbox is an ephemeral Linux VM in an environment. Create it, execSandbox commands, snapshot with checkpoints, and destroy it when the task is done. Sandboxes are Priority Boarding.

Railway has no labels and sandboxes have no names. Identity is the Railway sandbox id. There is no in-place update — changing environment, region, idleTimeoutMinutes, networkIsolation, template, or variables replaces the Sandbox.

Create a Sandbox

Pass a Project (or Environment). Alchemy waits until the sandbox is RUNNING and ready to exec.

const site = yield* Railway.Project("Site");
const box = yield* Railway.Sandbox("Box", {
  environment: site,
});

Changing environment or region replaces the Sandbox

A new VM is created. The old sandbox is destroyed.

Idle timeout

Railway auto-destroys a sandbox after it sits idle. Exec and SSH reset the timer; processes inside do not. Hobby/Pro default is 30 minutes (max 120). Trial/Free default and max is 5.

const box = yield* Railway.Sandbox("Box", {
  environment: site,
  idleTimeoutMinutes: 5,
});

Changing idleTimeoutMinutes replaces the Sandbox

There is no sandbox update API.

Variables

Baked into the sandbox at create time. Available to every command.

const box = yield* Railway.Sandbox("Box", {
  environment: site,
  variables: { NODE_ENV: "production" },
});

Template

Boot from a named checkpoint, or from build instructions.

const box = yield* Railway.Sandbox("Box", {
  environment: site,
  template: { name: "after-deps" },
});

Exec

Run a command after deploy with execSandbox or Exec.

const result = yield* Railway.execSandbox({
  sandboxId: box.sandboxId,
  environmentId: box.environmentId,
  command: "echo hello",
});

Module-scope declarations

Resource-valued props accept the resource or an Effect producing it.

src/box.ts

import * as Railway from "alchemy/Railway";

export const Site = Railway.Project("Site");
export const Box = Railway.Sandbox("Box", {
  environment: Site,
  idleTimeoutMinutes: 10,
});