Give Your Coding Agents a Cloud Sandbox

RWX sandboxes let you execute code in isolated cloud environments—useful for running complex setups or testing untrusted AI-generated code. While sandboxes work great for any developer workflow, they're particularly well-suited for coding agents.

Why Sandboxes Work Well for Agents

RWX builds tools for humans first. The same properties that make sandboxes fast and ergonomic for developers (content-based caching, file syncing, reproducible environments) happen to be exactly what coding agents need too.

The sandbox model keeps your agent running locally while offloading execution to the cloud. This "agent outside" approach gives you:

  • Full local control: Your agent runs on your machine, with your configuration, your tools, and your oversight
  • Fast cloud execution: RWX's content-based caching means sandbox environments spin up in seconds, not minutes
  • Reproducible environments: The same run definitions you use for CI work for sandboxes, so your agent tests against the same environment as your pipelines

This tight feedback loop between local development and cloud execution is central to how RWX tooling works—sandboxes just extend that pattern to agent workflows.

Getting Started

1. Initialize a Sandbox Configuration

rwx sandbox init

This creates .rwx/sandbox.yml with a starter template. Customize it for your project's environment—the same task definitions you'd use for CI work here.

A minimal sandbox configuration looks like this:

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

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

tasks:
  - key: code
    call: git/clone 2.0.3
    with:
      preserve-git-dir: true
      repository: https://github.com/your-org/your-repo.git
      ref: ${{ init.commit-sha }}
      github-token: ${{ github.token }}

  - key: sandbox
    use: code
    run: rwx-sandbox

A more complex example with language dependencies and background processes can be seen below.

2. Execute Commands in the Sandbox

rwx sandbox exec -- npm test

Your local changes are automatically synced up to the sandbox before execution, and synced back down after execution. The sandbox persists between commands, so subsequent calls reuse the same environment.

Working with Coding Agents

Parallel Agents with Git Worktrees

Sandboxes are uniquely identified by working directory, git branch, and config file. This means agents running in separate git worktrees automatically get isolated sandboxes:

repo/               → sandbox A
repo-worktree-1/    → sandbox B
repo-worktree-2/    → sandbox C

Each agent can execute commands in its own sandbox without interference.

Teaching Your Agent About Sandboxes

Consider defining a custom skill that tells your coding agent how to use RWX sandboxes:

---
name: rwx-sandbox
description: Run commands in RWX cloud sandbox. Use when user mentions "sandbox".
---

# RWX Sandbox

Run `rwx sandbox --help` for command documentation. Use `--help` on subcommands for details.

When finished using the sandbox, run `rwx sandbox stop`.

Pre-warming Sandboxes

For environments with complex startup (background services, large dependencies), pre-start the sandbox:

rwx sandbox start --wait

Most of the time, lazy startup is fast enough thanks to content-based caching—but pre-warming can help when you need the environment immediately available.

Managing Sandboxes

List all running sandboxes:

rwx sandbox list

Stop the current sandbox:

rwx sandbox stop

Stop all sandboxes:

rwx sandbox stop --all

Reset to a fresh state (discarding any changes):

rwx sandbox reset

Sandboxes automatically stop after 30 minutes of inactivity, but the rwx-sandbox directive in the sandbox.yml file supports the following flags for customizing the timeout:

FlagDefaultDescription
--attachment-timeout30mHow long to wait for a user to attach to the sandbox before stopping it
--session-timeout30mMaximum duration of the sandbox session once attached

Timeouts are specified as durations like 5m or 1h.

Example with Language Dependencies and Background Processes

Below is a more complete/realistic example of a sandbox.yml file that includes language dependencies and background processes.

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

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

tasks:
  - key: code
    call: git/clone 2.0.3
    with:
      preserve-git-dir: true
      repository: https://github.com/your-org/your-repo.git
      ref: ${{ init.commit-sha }}
      github-token: ${{ github.token }}

  - key: tool-versions
    use: code
    call: rwx/tool-versions 1.0.6
    filter:
      - .tool-versions

  - key: node
    call: nodejs/install 1.1.11
    with:
      node-version: ${{ tasks.tool-versions.values.node }}

  - key: npm-install
    use: [code, node]
    run: npm install
    filter:
      - package.json
      - package-lock.json

  - key: docker-images
    use: code
    docker: preserve-data
    run: docker compose pull
    filter:
      - docker-compose.yml

  - key: sandbox
    use: [code, docker-images, npm-install]
    docker: true
    background-processes:
      - key: start-databases
        run: docker compose up
        ready-check: rwx-docker-ready-check
    run: |
      npm run migrate
      rwx-sandbox

For more complex setups, reference the CI workflow guide.

Next Steps