chat2shell

chat2sbx connects ChatGPT to disposable Docker Sandbox microVMs running on your own machine. ChatGPT gets a real shell, files, packages, servers, and Docker without getting your host shell or host Docker daemon.

If you already use Docker Sandboxes, chat2sbx adds the ChatGPT-facing control layer: create and reuse sandboxes, keep workspaces between sandbox instances, run long commands, and expose local ports.

Quick start

Prerequisites

• Node.js 24+

• Docker Sandboxes (sbx)

• OpenAI Secure MCP Tunnel access to use chat2sbx from ChatGPT

Install chat2sbx and sign in to Docker Sandboxes:

npm install --global chat2sbx
sbx login

On a headless or non-interactive host, initialize the Docker Sandboxes network policy before setup:

sbx policy init balanced

Interactive machines prompt for a network preset on first use, so you can skip that command there. Then prepare the sandbox template and start chat2sbx:

chat2sbx setup
chat2sbx serve

You can check it from another terminal:

chat2sbx status

The MCP server listens on http://127.0.0.1:18788/mcp by default.

Connect ChatGPT

Create a tunnel and runtime API key in OpenAI Platform, then run the official tunnel-client against the local MCP server:

export CONTROL_PLANE_TUNNEL_ID='tunnel_...'
export CONTROL_PLANE_API_KEY='...'
export MCP_SERVER_URL='http://127.0.0.1:18788/mcp'

tunnel-client doctor --explain
tunnel-client run

Keep the tunnel client running. In ChatGPT, create a developer-mode app, choose Tunnel as the connection, and select the same tunnel. OpenAI's Secure MCP Tunnel guide covers tunnel setup and permissions.

Then try:

Create a sandbox, run uname -a and docker version inside it, and show me the results.

If ChatGPT can run both commands, the connection is ready.

Related MCP server: anvil

How it works

ChatGPT
  │
  │ MCP
  ▼
Secure MCP Tunnel
  │
  ▼
chat2sbx
  │
  └─ Docker Sandbox microVM
       ├─ workspace
       ├─ shell and dev tools
       └─ private Docker Engine

The sandbox is where the agent does its work. Your host shell, sudo, Docker daemon, and arbitrary host paths stay outside that boundary. See Architecture for the detailed model.

Features

• Create disposable Docker Sandbox microVMs from ChatGPT

• Keep working files across sandbox replacements

• Run file, repository, and shell tasks, including long-running commands

• Use a private Docker Engine inside each sandbox

• Expose ports for services running inside a sandbox

CLI

chat2sbx setup                         Prepare the sandbox template
chat2sbx serve                         Run the local MCP server
chat2sbx status                        Check local service status
chat2sbx workspace list                List workspaces
chat2sbx sandbox list                  List sandboxes
chat2sbx sandbox destroy <id>          Destroy a sandbox

Repository work happens inside the sandbox. Clone repositories there instead of mounting arbitrary host directories.

Workspaces survive sandbox replacement so you can continue where you left off. See Architecture for retention details.

Configuration

Most users can use the defaults. Common options are:

• CHAT2SBX_HOST and CHAT2SBX_PORT to change the local MCP bind address

• CHAT2SBX_MAX_ACTIVE_SANDBOXES to limit active sandboxes

• ~/.chat2sbx/AGENTS.md for instructions shared across sandboxes

The default data directory is ~/.chat2sbx.

Security

The MCP server binds to loopback by default and has no built-in authentication. Use an access-controlled transport such as Secure MCP Tunnel instead of exposing it directly to an untrusted network.

Services published with sandbox_expose do not get authentication from chat2sbx. Read SECURITY.md before exposing chat2sbx or sandbox services beyond your machine.

Troubleshooting

If ChatGPT cannot reach chat2sbx, start with:

chat2sbx status
tunnel-client doctor --explain

For a failed sandbox:

chat2sbx sandbox list
chat2sbx sandbox destroy <id>

Use the underlying sbx CLI for Docker Sandbox diagnostics and reset/prune operations.

Documentation

• Architecture — runtime model, trust boundaries, and lifecycle details

• Security — security scope and vulnerability reporting

• Contributing — development and contribution guide

• Tests — test layout and E2E requirements

• Roadmap — planned product direction

Project status

chat2sbx is early-stage software. The core workflow is usable, but interfaces may change as the project gets more real-world use. Bug reports and workflow feedback are welcome.

License

MIT. Third-party notices are listed in THIRD_PARTY_NOTICES.md.