> ## Documentation Index
> Fetch the complete documentation index at: https://rwx.reclear.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/quickstart)
and keep your terminal in its `rwx-quickstart` clone. If you followed
[catching and fixing a local regression](/test-local-changes),
restore the calculation first. Check:

```sh theme={null}
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:

```yaml theme={null}
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:

```sh theme={null}
rwx lint .rwx/sandbox.yml
```

Expected output:

```text theme={null}
Checked 1 file and found 0 problems.
```

## 2. Run the project tests

```sh theme={null}
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:

```text theme={null}
Test Suites: 2 passed, 2 total
Tests:       20 passed, 20 total
```

<img src="https://mintcdn.com/rwx/5R4hL8ab__WRzwOm/images/sandbox-tasks.jpg?fit=max&auto=format&n=5R4hL8ab__WRzwOm&q=85&s=35956857e5470a903975b3589284c13b" alt="Sandbox definition with code, node, npm-install, and sandbox tasks" width="1120" height="370" data-path="images/sandbox-tasks.jpg" />

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:

```sh theme={null}
printf 'local input\n' > sandbox-note.txt
```

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

```sh theme={null}
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:

```text theme={null}
local input
linux v24.8.0
```

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

```sh theme={null}
cat sandbox-note.txt
```

Expected contents:

```text theme={null}
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](https://www.rwx.com/docs/sandboxes).

Running the append command again adds another `cloud edit` line.

## 4. Stop the sandbox

From the same clone and branch, run:

```sh theme={null}
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](https://www.rwx.com/docs/guides/ci). See the
[sandbox guide](https://www.rwx.com/docs/sandboxes) for longer-lived sessions and
additional environment setup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.