Termos Sandbox

Multi-instance browser automation with AI coding agents (Claude, Codex, Gemini, OpenCode).

A daemon-based system where each Chrome window runs an independent AI coding agent in a user-selected directory.

Installation

npm install -g @termosdev/sandbox

Quick Start

# Start daemon (foreground mode)
termos-sandbox launch

# Start in background (detached mode)
termos-sandbox launch -d

# List all running windows
termos-sandbox list

# Stop the daemon
termos-sandbox stop

How It Works

1. Launch the daemon - Starts the Termos backend service
2. Chrome window opens - With the Termos extension sidepanel
3. Select an agent - Choose from Claude, OpenCode, Codex, or Gemini
4. Pick a directory - The agent will work in that directory
5. Start coding - The agent runs in an isolated terminal

Supported Agents

| Agent | CLI Command | Description | |-------|------------|-------------| | Claude | claude | Anthropic's Claude Code CLI | | OpenCode | opencode | OpenCode AI assistant | | Codex | codex | OpenAI Codex CLI | | Gemini | gemini | Google Gemini CLI |

Architecture

Chrome Window 1              Chrome Window 2
     |                            |
Extension Sidepanel          Extension Sidepanel
     |                            |
WebSocket: localhost:7890 (shared daemon)
     |
Daemon (single process)
  |-- Window Registry (windowId -> directory)
  |-- Process Pool (windowId -> Agent process)
  +-- HTTP Server (dashboard + APIs)

Features

• Multi-agent support - Claude, OpenCode, Codex, and Gemini
• Window-based isolation - each window is independent
• Multi-directory support - run agents in multiple directories simultaneously
• Session resume - resume previous sessions with the same agent
• Graceful shutdown - proper cleanup on exit
• Auto-reconnect - extension reconnects automatically

Chrome Extension

The extension is bundled with the package. After launching the daemon:

1. Open chrome://extensions in Chrome
2. Enable "Developer mode"
3. Click "Load unpacked"
4. Select the extension folder from node_modules:

   node_modules/@termosdev/sandbox/chrome-extension

API

The daemon exposes HTTP and WebSocket APIs on port 7890:

# Check daemon status
curl http://localhost:7890/api/status

# View logs
curl http://localhost:7890/api/logs?lines=50

# Launch a new Chrome window
curl -X POST http://localhost:7890/api/launch-window

Environment Variables

The daemon sets these when spawning agents:

TERMOS_WINDOW_ID=123              # Which window owns this process
TERMOS_DAEMON_PORT=7890           # Daemon port

Requirements

• Node.js 18+
• Chrome browser
• At least one AI agent CLI installed (claude, opencode, codex, or gemini)

License

MIT