room-sandbox 1.2.0

Dockerized multi-agent sandbox for room
room-sandbox-1.2.0 is not a library.

room-sandbox

Dockerized multi-agent sandbox for room. Sets up isolated development environments where multiple AI agents collaborate on a codebase via room-ralph.

Each agent gets its own clone of the target repo, runs inside a shared Docker container, and communicates through a room instance. Agents are assigned roles (coder, reviewer, manager) that determine their behavior and tool access.

Install

cargo install room-sandbox

Quick Start

mkdir my-sandbox && cd my-sandbox
room-sandbox init

The interactive wizard walks you through:

  • Repo — git URL, SSH, HTTPS, or shorthand (org/repo)
  • Languages — rust, node, python (auto-detected from repo)
  • Utilities — glow, playwright, just, mise, terraform, docker, kubectl, etc.
  • Agents — names and roles (coder, reviewer, manager)
  • Auth — GitHub account selection (supports multiple gh accounts), PAT, or SSH

You can also run room-sandbox init inside an existing git repo — it auto-detects the remote URL and languages from marker files (Cargo.toml, package.json, etc.).

Once initialized, start your agents:

room-sandbox claude r2d2             # run claude interactively once to /login
room-sandbox agent start --all       # start all agents in background
room-sandbox tui                     # open the room TUI to observe and interact

First run: Agents use Claude Code under the hood. You need to authenticate once by running room-sandbox claude <any-agent> and typing /login. The auth persists across all agents via a shared Docker volume.

Config

Everything is driven by sandbox.toml, which can be committed to your project repo so teammates can room-sandbox apply to get a working sandbox:

[project]
repo = "git@github.com:org/project.git"
container_name = "sandbox-project"

[[agent]]
name = "r2d2"
role = "coder"

[[agent]]
name = "saphire"
role = "reviewer"

[[agent]]
name = "ba"
role = "manager"

[room]
default = "dev"

[auth]
method = "gh-cli"
mount_ssh = true
gh_account = "myaccount"

[environment]
languages = ["node", "rust"]
utilities = ["glow", "just", "docker"]

Commands

Setup

Command Description
room-sandbox init Interactive wizard — scaffolds sandbox.toml and builds everything
room-sandbox apply Diff config against state, show plan, apply on confirmation
room-sandbox clean Remove all generated artifacts, keep sandbox.toml

Agents

Command Description
room-sandbox agent add <name> Add an agent (prompts for role, auto-applies)
room-sandbox agent remove <name> Remove an agent and its workspace
room-sandbox agent list Show agents with role and status (running/ready/missing)
room-sandbox agent start <names...> Start agents in background
room-sandbox agent start --all Start all agents
room-sandbox agent start -t <names...> Start and tail multiplexed output
room-sandbox agent stop <names...> Stop agents (kills process group)
room-sandbox agent stop --all Stop all agents
room-sandbox agent restart <names...> Restart agents

Interactive

Command Description
room-sandbox tui Open the room TUI
room-sandbox tui --as helix Join as a specific username
room-sandbox shell [name] Bash into the container (optionally into an agent's workspace)
room-sandbox shell --root Shell in as root
room-sandbox claude <name> Run Claude Code interactively in an agent's workspace
room-sandbox claude <name> -- --model sonnet Pass extra args to Claude

Container

Command Description
room-sandbox up Start the container
room-sandbox down Stop the container
room-sandbox logs Tail container logs

Agent Roles

Roles map to room-ralph personalities which set system prompts and tool profiles:

Role Personality Behavior
coder coder Picks up tasks, writes code, runs tests, opens PRs
reviewer reviewer Reviews PRs, checks quality, leaves feedback — does not write code
manager coordinator Breaks down goals into tasks, manages the taskboard, coordinates agents

Directory Layout

my-sandbox/
  sandbox.toml              # config (committed)
  .room-sandbox/            # generated artifacts (gitignored)
    .sandbox-state.json
    .env
    Dockerfile
    docker-compose.yml
    entrypoint.sh
    claude-wrapper.sh
    workspaces/
      r2d2/                 # git clone of target repo
      saphire/
      ba/

Utilities

The init wizard lets you select utilities to install in the container:

Utility Description
glow Markdown reader
playwright Browser automation
just Command runner
mise Tool version manager
proto Toolchain manager
pulumi Infrastructure as code
terraform Infrastructure as code
ansible Automation (auto-installs python)
aws-cli AWS command line
docker Docker-in-Docker CLI
kubectl Kubernetes CLI
yq YAML processor

Security

  • SSH agent forwarding — when SSH is enabled, only the agent socket is forwarded into the container. Private keys never leave the host.
  • Agent name validation — names are restricted to [a-zA-Z0-9_-] to prevent command injection.
  • Docker socket — only mounted if you explicitly select the docker utility. Be aware this grants container access to the host Docker daemon.

Prerequisites

License

MIT