Chat2sbx

chat2sbx

Give ChatGPT a computer you can safely throw away.

Quick start · Architecture · Security · Contributing · Roadmap

What is chat2sbx?

chat2sbx is a lightweight MCP control plane that gives ChatGPT a capable development environment inside disposable Docker Sandbox microVMs.

Each sandbox gets its own shell, approved workspace, CodexPro process, and private Docker Engine. The host shell and host Docker daemon stay outside the execution boundary.

Why use it?

• Capable by default — run shell commands, install packages, start servers, and use Docker inside the sandbox.
• Isolated from the host — ChatGPT never receives raw host shell, host sudo, or host Docker access.
• Explicit workspace access — arbitrary host paths require approval; clone mode keeps edits private by default.
• Built for agent workflows — stable sandbox/workspace IDs, long-running Bash sessions, port exposure, and reusable global instructions work across conversations.

How it works

ChatGPT
  │
  │ MCP
  ▼
Secure MCP Tunnel
  │
  ▼
chat2sbx (host, loopback only)
  │
  ├─ workspace / approval / sandbox registry
  │
  └─ Docker Sandbox microVM
       ├─ approved workspace
       ├─ CodexPro
       ├─ unrestricted sandbox shell
       └─ private Docker Engine

The diagram is intentionally simplified. See Architecture for the trust boundaries, lifecycle rules, Bash session contract, and workspace model.

Prerequisites

• Node.js 24+
• Docker Sandboxes (sbx)
• For ChatGPT access: OpenAI Secure MCP Tunnel access and the tunnel client configured for your account

Quick start

1. Install chat2sbx

npm install --global chat2sbx

2. Prepare the sandbox template

Start without a tunnel first to verify the local runtime:

CHAT2SBX_ENABLE_TUNNEL=0 chat2sbx setup

setup checks Docker Sandboxes and creates the pinned chat2sbx-codexpro:0.30.0 template when needed.

3. Start the MCP server

CHAT2SBX_ENABLE_TUNNEL=0 chat2sbx serve

In another terminal:

CHAT2SBX_ENABLE_TUNNEL=0 chat2sbx status

The local MCP endpoint binds to loopback by default.

4. Connect ChatGPT

Follow OpenAI's Secure MCP Tunnel guide, configure the tunnel client, tunnel ID, and key file, then run:

chat2sbx setup
chat2sbx serve

By default chat2sbx expects:

Tunnel client   ~/.local/bin/tunnel-client
Tunnel ID       ~/.secrets/tunnel-client/tunnel-id
Tunnel key      ~/.secrets/tunnel-client/key

Override these locations with environment variables when your setup differs. See Configuration.

Example workflow

Once connected, ChatGPT can create an isolated workspace and use the returned sandbox_id for subsequent tools:

sandbox_create
  -> bash / read / write / search / ...
  -> bash_poll for long-running commands
  -> sandbox_expose to preview a web service
  -> sandbox_destroy when the environment is no longer needed

sandbox_create can optionally set a memory ceiling such as 512m or 4g. When reopening an existing sandbox, call sandbox_get first so its current state and any global sandbox instructions are loaded.

A typical long-running command looks like:

bash
  -> { session_id: "bash_...", status: "running", output: "..." }

bash_poll
  -> { sandbox_id: "sbx_...", session_id: "bash_..." }

Workspace modes

Mode	Host interaction	Best for
managed	chat2sbx-owned persistent workspace	Disposable or standalone agent work
clone	Private clone of an approved host repository	Safe default for existing repositories
direct	Read/write access to one approved host directory	Work that must immediately affect the host checkout

clone is the default for approved host repositories. Use direct only when you intentionally want sandbox commands to modify the approved host directory.

Resource controls and global instructions

Resource controls are optional. By default chat2sbx leaves Docker Sandboxes resource sizing unchanged and allows any number of active sandboxes. Operators can:

• pass memory to sandbox_create with values such as 512m or 4g;
• set maxActiveSandboxes in ~/.chat2sbx/config.json or override it with CHAT2SBX_MAX_ACTIVE_SANDBOXES;
• add ~/.chat2sbx/AGENTS.md to provide global agent instructions returned by sandbox_create and sandbox_get.

Global instructions are advisory text for agents. They are not copied into a workspace, interpreted as commands, or enforced as security policy. See Architecture for the exact lifecycle and resource semantics.

Security model

chat2sbx is designed around a simple boundary: the agent is powerful inside the microVM, not on the host.

• CodexPro and unrestricted Bash run inside Docker Sandboxes, never directly on the host.
• Host paths are not mounted unless they are managed by chat2sbx or explicitly approved.
• The MCP server has no built-in authentication and binds to loopback by default. Do not expose it directly to an untrusted network.
• sandbox_expose publishes a sandbox port without adding authentication; treat the exposed service accordingly.
• Tunnel credentials and internal CodexPro bearer tokens are not returned through MCP.

Read Architecture for the canonical technical model and Security for vulnerability reporting and expected security boundaries.

CLI

chat2sbx setup                         Check prerequisites and prepare the sandbox template
chat2sbx serve                         Run the MCP gateway and tunnel client in the foreground
chat2sbx status                        Show service, MCP, and tunnel readiness
chat2sbx workspace list                List known workspaces
chat2sbx workspace add <path>          Register a host workspace
chat2sbx approval list                 List pending host-path approvals
chat2sbx approval approve <id>         Approve a host-path request
chat2sbx approval reject <id>          Reject a host-path request

Configuration

The defaults are intentionally small. .env.example contains the complete set of environment overrides.

Variable	Default	Purpose
CHAT2SBX_HOST	127.0.0.1	MCP bind address
CHAT2SBX_PORT	18788	MCP port
CHAT2SBX_DATA_ROOT	~/.chat2sbx	Persistent chat2sbx data
CHAT2SBX_STATE_DIR	<data root>/state	Runtime state directory
CHAT2SBX_WORKSPACE_ROOT	<data root>/workspaces	Managed workspace directory
CHAT2SBX_DATABASE_PATH	<state dir>/chat2sbx.sqlite	SQLite state database
CHAT2SBX_ALLOWED_HOST_ROOTS	~/repositories	Roots eligible for host workspace approval
CHAT2SBX_ENABLE_TUNNEL	1	Set to 0 for local-only mode
CHAT2SBX_TUNNEL_CLIENT	~/.local/bin/tunnel-client	Secure MCP Tunnel client path
CHAT2SBX_SECRET_DIR	~/.secrets/tunnel-client	Tunnel ID/key directory
CHAT2SBX_MAX_ACTIVE_SANDBOXES	unlimited	Optional active sandbox limit

The same sandbox limit can be stored in ~/.chat2sbx/config.json as maxActiveSandboxes; the environment variable takes precedence. chat2sbx status shows the effective limit and active count. Configuration is read when chat2sbx serve starts.

Global sandbox instructions live at ~/.chat2sbx/AGENTS.md by default. Changes to that file are read on the next sandbox_create or sandbox_get and do not require a server restart.

Documentation

Document	Purpose
Architecture	Trust boundaries, runtime ownership, workspace modes, lifecycle, and Bash sessions
Security	Vulnerability reporting and security scope
Contributing	Development setup, validation, and contribution workflow
Tests	Unit/integration/E2E boundaries and commands
Roadmap	Intended product direction
Code of Conduct	Community participation expectations

Project status

chat2sbx is early-stage software. The core sandbox boundary and workflow are usable, but interfaces may still change as the project is tested with real users.

If you try it, bug reports and concrete workflow feedback are especially useful. Use the repository's issue templates so reports include enough context to reproduce the problem.

License

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