From npm install to your first preview URL in under 90 seconds.

A single-page quickstart. Install the CLI, spin up a workspace pinned to a branch, look at the preview URL. The full CLI reference and config schema are linked below.

Install the CLI

The CLI is a Node package. Everything else (runtime, editors, snapshots) is downloaded on first use.

$ npm i -g railrocket
$ railrocket --version
railrocket 0.6.4

$ railrocket login
opens browser → confirm in dashboard → writes ~/.railrocket/credentials

Mac, Linux, and Windows are all supported on Node 18+. On Windows we recommend running the CLI from WSL.

Your first workspace

From the directory containing a Git repo:

$ railrocket workspace create
  reading railrocket.yml... (none found, using defaults)
  spinning up acme-web @ main...
    ↳ snapshot restore: 0.4s
    ↳ npm install: 11.3s
    ↳ ready in 12.8s (first run)
  ➤ attach: https://railrocket.dev/w/you/acme-web/main

First runs take longer because we cache nothing yet. Subsequent runs use the snapshot, typically under 1.4 s.

Open the attach URL to use the workspace in your browser. Or run railrocket ssh to attach over SSH from your terminal.

railrocket.yml

Commit a railrocket.yml at the repo root to make the workspace shape reproducible. Every dev gets the same workspace, every branch.

# railrocket.yml
name: acme-web
runtime: node-20

setup:
  - npm install
  - npm run db:migrate

expose:
  - 3000  # vite dev server
  - 5432  # postgres

postgres:
  version: 16
  seed: ./scripts/seed.sql

env:
  DATABASE_URL: postgres://app@localhost/acme
  NODE_ENV: development

Workspaces

A workspace is an isolated environment running your code. It comes with a file system, a shell, a runtime, optionally a database, and exposed ports. You can attach to it from a browser, a desktop editor (VS Code, JetBrains, Cursor), or SSH.

Workspaces auto-pause after 5 minutes of idle to save compute hours. They resume in milliseconds when you reconnect.

Branch mapping

One workspace per Git branch. Switching branches in your local checkout doesn’t affect the cloud — cloud workspaces follow the branches you tell them to. The mapping happens automatically when you push.

$ git push -u origin feat/login-redirect
  remote: railrocket: workspace spinning up...
  remote: railrocket: ready — https://feat-login-redirect.acme-web.railrocket.dev

Sharing

Click the Share button in the IDE topbar (or run railrocket share). You get a URL that anyone with repo access can open to attach to your workspace, same files and terminal as you.

Read-only mode is recommended for design reviews; terminal access is opt-in.

Preview URLs

Every workspace gets a public URL of the form https://<branch>.<repo>.railrocket.dev. Anything exposed via the expose list in railrocket.yml is reachable from the preview URL.

Postgres workspaces

Added in v0.6.4. Set postgres: in your railrocket.yml and a fresh Postgres instance is provisioned per workspace, seeded from your seed.sql if provided. Cross-workspace data isolation is automatic.

CLI commands

The commands you’ll use most:

• railrocket login — authenticate the CLI
• railrocket workspace create [branch] — spin up a workspace
• railrocket workspace list — see all active workspaces
• railrocket workspace stop <name> — pause (keep state)
• railrocket workspace destroy <name> — delete
• railrocket attach <name> — open in browser
• railrocket ssh <name> — attach via SSH
• railrocket share <name> — generate share link
• railrocket logs --tail — stream workspace logs

Editors & SSH

The default is VS Code in the browser. To use a desktop editor:

• VS Code desktop: railrocket vscode <name> — opens local VS Code attached to the remote workspace.
• JetBrains: install JetBrains Gateway; use the RailRocket plugin to connect.
• Cursor: works the same as VS Code with railrocket cursor <name>.
• Vim / Neovim / Emacs: railrocket ssh <name> drops you into the workspace shell.

Getting help

For docs that aren’t here yet, email support@railrocket.dev. We don’t run a community Slack — we found support quality is higher when conversations stay in writing.