Run commands in a cloud sandbox

Reuse one cloud environment across commands, sync file edits, and stop the session.

In this tutorial, run tests from the quickstart’s sample project in a persistent cloud environment. Reuse that sandbox for a second command, send a local file to it, and bring back a cloud edit. Finish by stopping the sandbox.

Before you start

Complete the quickstart and keep your terminal in its rwx-quickstart clone. If you followed catching and fixing a local regression, restore the calculation first. Check:

git diff -- src/index.js

It should print nothing. This lesson uses a POSIX shell on macOS, Linux, or WSL. RWX supplies Node.js and npm in the cloud.

1. Add the sandbox configuration

Create .rwx/sandbox.yml with this definition:

on:
  cli:
    init:
      commit-sha: ${{ event.git.sha }}

base:
  image: ubuntu:24.04
  config: rwx/base 1.2.0

tasks:
  - key: code
    call: git/clone 2.2.0
    with:
      repository: https://github.com/rwx-cloud/ci-examples.git
      ref: ${{ init.commit-sha }}
      preserve-git-dir: true

  - key: node
    call: nodejs/install 1.2.0
    with:
      node-version: "24.8.0"

  - key: npm-install
    use: [code, node]
    timeout: 3m
    run: npm ci --no-audit --no-fund
    filter:
      - package.json
      - package-lock.json

  - key: sandbox
    use: npm-install
    timeout: 5m
    run: rwx-sandbox --first-exec-timeout 2m --inactivity-timeout 2m

The first three tasks prepare the same project, Node.js version, and dependencies as the quickstart. preserve-git-dir: true retains Git metadata for file syncing. The final task starts the persistent sandbox instead of running one CI check.

The sandbox stops after two minutes of inactivity. The five-minute task timeout also bounds this short exercise. Stop it explicitly when you finish.

Check the definition:

rwx lint .rwx/sandbox.yml

Expected output:

Checked 1 file and found 0 problems.

2. Run the project tests

rwx sandbox exec -- npm test -- --runInBand

RWX finds .rwx/sandbox.yml, prepares its tasks, and runs the command. Keep the printed sandbox URL: it opens the setup tasks in RWX Cloud.

Look for this test summary:

Test Suites: 2 passed, 2 total
Tests:       20 passed, 20 total

The setup may reuse Node.js and dependency results from earlier runs. The sandbox task remains available for your next command.

3. Send a file and receive a cloud edit

Create sandbox-note.txt in the clone:

printf 'local input\n' > sandbox-note.txt

Run this command before the sandbox’s inactivity timeout expires:

rwx sandbox exec -- node -e 'const fs = require("node:fs"); console.log(fs.readFileSync("sandbox-note.txt", "utf8").trim()); fs.appendFileSync("sandbox-note.txt", "cloud edit\n"); console.log(process.platform, process.version);'

The CLI should report Reconnecting to existing sandbox. The command prints:

local input
linux v24.8.0

Then RWX reports that it pulled sandbox-note.txt back from the sandbox. Read your local copy:

cat sandbox-note.txt

Expected contents:

local input
cloud edit

The sandbox read a file that was still untracked locally, appended a line in Linux, and returned that edit to your machine. Sandbox commands sync local changes up before execution and cloud changes down afterward.

Running the append command again adds another cloud edit line.

4. Stop the sandbox

From the same clone and branch, run:

rwx sandbox stop
rwx sandbox list

The stop command should confirm Stopped sandbox. Check that the list has no active entry for this clone’s quickstart branch and .rwx/sandbox.yml file. Other sandboxes you have started may still appear.

Your sandbox-note.txt remains local after the sandbox stops. You can now use one cloud environment across commands and bring its file edits back to your working directory.

If a step fails

What you see	What to do
The CLI cannot find a sandbox definition	Run from the example clone and check that the file is .rwx/sandbox.yml
Tests fail	Restore the original src/index.js calculation and run the test command again
A later command starts a new sandbox	The earlier session may have reached its inactivity timeout; complete the commands consecutively
The local note has several cloud edit lines	The append command ran more than once; rewrite the note with the printf command before repeating the round trip

For a larger project, adapt the setup tasks using the CI workflow guide. See the sandbox guide for longer-lived sessions and additional environment setup.