agent-sandbox

Give AI agents direct access to a real terminal inside a Docker container.

Why

AI agents often need to run shell commands, start dev servers, or interact with CLI tools. Agent Sandbox gives them a real terminal (via tmux inside Docker) instead of simulating one. A single sandbox can run multiple panes concurrently — dev server, coding agent, test runner, and shell — all at once.

create  <->  delete    sandbox lifecycle
attach  <->  detach    open/close terminal panes
read    <->  write     see terminal output / send keystrokes

Agent -> write -> tmux send-keys    -> Application
Agent <- read  <- tmux capture-pane <- Application

Table of Contents

• Installation
• Quick Start
• CLI Reference
• MCP Reference
• License

Installation

Prerequisites: Docker running locally, Node.js 18+

CLI

# via npm
npm install -g @agent-sandbox/cli

# or install the standalone binary (no Node.js required)
curl -fsSL https://raw.githubusercontent.com/usamaasfar/agent-sandbox/main/install.sh | sh

MCP

npm install -g @agent-sandbox/mcp

Add to your MCP config:

{
  "mcpServers": {
    "agent-sandbox": {
      "command": "npx",
      "args": ["@agent-sandbox/mcp"]
    }
  }
}

Quick Start

# Create a sandbox
agent-sandbox create
# => sandboxId: abc123

# Open a terminal pane
agent-sandbox attach abc123
# => paneId: %0

# Run a command
agent-sandbox write abc123 %0 "echo hello world"

# Read the output
agent-sandbox read abc123 %0

# Clean up
agent-sandbox detach abc123 %0
agent-sandbox delete abc123

CLI Reference

agent-sandbox <command> [arguments] [options]

create

Start a new sandbox container.

agent-sandbox create [options]

Returns: sandboxId

Option	Default	Description
--name	—	Optional name for the sandbox
--image	agent-sandbox	Custom base image
--volume	—	Optional name of a Docker volume to mount at /home/sandbox

delete

Stop and remove a sandbox. All state is lost.

agent-sandbox delete <sandboxId>

Argument	Description
<sandboxId>	Sandbox to delete

attach

Open a new terminal pane inside a sandbox.

agent-sandbox attach <sandboxId>

Returns: paneId

Argument	Description
<sandboxId>	Sandbox to attach to

detach

Close a terminal pane.

agent-sandbox detach <sandboxId> <paneId> [options]

Argument	Description
<sandboxId>	Sandbox ID
<paneId>	Pane to detach

Option	Default	Description
--mode	kill	kill destroys the pane entirely; close stops the foreground process but keeps the pane alive

read

Capture current terminal output as plain text.

agent-sandbox read <sandboxId> <paneId> [options]

Returns: pane output (plain text)

Argument	Description
<sandboxId>	Sandbox ID
<paneId>	Pane to read from

Option	Default	Description
--tail	—	Capture the last N lines of scrollback history
--head	—	Return the first N lines of the captured output

write

Send keystrokes to a pane followed by Enter. Use \x03 for Ctrl+C.

agent-sandbox write <sandboxId> <paneId> <input>

Argument	Description
<sandboxId>	Sandbox ID
<paneId>	Pane to write to
<input>	Input to send

MCP Reference

@agent-sandbox/mcp wraps the CLI. Each MCP tool maps 1:1 to a CLI command.

MCP tool	CLI equivalent
as_create	agent-sandbox create
as_delete	agent-sandbox delete <sandboxId>
as_attach	agent-sandbox attach <sandboxId>
as_detach	agent-sandbox detach <sandboxId> <paneId>
as_read	agent-sandbox read <sandboxId> <paneId>
as_write	agent-sandbox write <sandboxId> <paneId> <input>

License

MIT