rwx sandbox exec
Execute a command in a persistent cloud sandbox environment.
Usage
rwx sandbox exec [config-file] -- <command> [flags]
Description
Sandboxes are isolated, reproducible environments running in RWX cloud infrastructure. They persist between commands, allowing you to run multiple commands against the same environment without rebuilding each time.
Sandbox reuse
Sandboxes are reused by default. When you run rwx sandbox exec, the CLI looks for an existing sandbox for your current branch and config file and reconnects to it if one exists. If none exists, a new one is started automatically. You can also pre-start a sandbox using rwx sandbox start to give it time to set up your environment before you need it. Most of the time, lazily starting a sandbox when executing a command is plenty fast, thanks to RWX's content-based caching.
To force a fresh sandbox — for example, to re-run setup tasks after changing a dependency or updating the sandbox configuration — pass --reset. This stops the existing sandbox and starts a new one before executing your command. You can also reset a sandbox independently using rwx sandbox reset.
File syncing
Before each command, local changes are automatically synced to the sandbox, and after the command completes, the sandbox's changes are synced back to your local machine. This includes staged changes, unstaged changes, and untracked files. Use --no-sync to skip this step if you want to run against the sandbox's original state.
The first exec against a newly-started sandbox also syncs back any files produced during setup tasks (for example, a Gemfile.lock or package-lock.json generated while installing dependencies), so your local working directory stays consistent with what the sandbox built. Subsequent execs only sync changes made by the command itself.
Note: Git LFS files cannot be synced and will generate a warning.
Config file
The sandbox configuration (default: .rwx/sandbox.yml) defines:
- Base image and dependencies
- Git repository to clone
- Any setup tasks that run before the sandbox becomes available
The config must include a task with run: rwx-sandbox which defines the sandbox entry point, and must be dependent on a task that uses git/clone with preserve-git-dir: true.
To generate a sandbox configuration file, you can use rwx sandbox init and then customize it to meet your repository's environment setup needs. The best practice is to commit this sandbox.yml file to your repo, to re-use that environment setup across your team.
Setup failures
If a setup task fails before the sandbox becomes available, rwx sandbox exec exits with an error and prints a diagnostic summary of what went wrong directly in the terminal. This summary is designed to give a coding agent everything it needs to self-heal — typically, a fix to the sandbox configuration or project files — without having to open the RWX UI. After addressing the root cause, run rwx sandbox exec --reset -- <command> to start a fresh sandbox; the failed run is not reused.
Arguments
[config-file]
The path to the sandbox configuration file. Defaults to .rwx/sandbox.yml.
<command>
(required) The command to execute in the sandbox. Must be preceded by --.
Options
-d, --dir <directory>
The directory your RWX configuration files are located in, typically .rwx. By default, the CLI traverses up until it finds a .rwx directory.
--id <run-id>
Use a specific run ID to target an existing sandbox session.
--no-sync
Skip syncing local changes before execution. Use this when you want to run against the sandbox's original state without your local modifications.
--open
Open the run in a browser after starting.
--reset
Stop the existing sandbox (if any) and start a new one before executing the command. Use this to re-run setup tasks after changes to the sandbox configuration or dependencies, or to recover from a failed setup.
Global Options
--output <format>
Output format: text or json. Defaults to text.
--access-token <token>
The access token for RWX. Defaults to the value of the $RWX_ACCESS_TOKEN environment variable.