Quick start

Understand it before you hand it to an AI

How boxes work, where your code and data go, what is kept, and how several repos and databases fit in: see the FAQ for engineers.

Receive app feedback after the AI finishes its turn

Start the native conversation with parallelsandbox-agent from parallelsandbox-mcp 0.5.5. Authenticate the native AI and ParallelSandbox first, then prepare a text file with your request. Choose one command for your AI and replace the CLI, project and request file with your own absolute paths:

The runner uses a new private native configuration directory. Supply ANTHROPIC_API_KEY for Claude, CODEX_API_KEY or OPENAI_API_KEY for Codex, or GEMINI_API_KEY with a valid provider endpoint for Gemini at runtime. Signing in to a different global CLI directory does not automatically authenticate this session. API keys stay out of the saved model/permission profile. ParallelSandbox sign-in authenticates its tools separately.

For Gemini headless execution, set GEMINI_CLI_TRUST_WORKSPACE=true before starting, only for the project you intend to trust; the runner saves this explicit choice and restores it when recovering the session.

npx -y --package parallelsandbox-mcp@0.5.5 parallelsandbox-agent start --provider codex \
  --cli /absolute/path/to/codex --cwd /absolute/path/to/project --prompt-file /absolute/path/to/request.txt
npx -y --package parallelsandbox-mcp@0.5.5 parallelsandbox-agent start --provider claude-code \
  --cli /absolute/path/to/claude --cwd /absolute/path/to/project --prompt-file /absolute/path/to/request.txt
npx -y --package parallelsandbox-mcp@0.5.5 parallelsandbox-agent start --provider gemini \
  --cli /absolute/path/to/gemini --cwd /absolute/path/to/project --prompt-file /absolute/path/to/request.txt

One persistent supervisor owns each conversation. Three drivers invoke the native Codex, Claude Code and Gemini CLIs. When the AI hands off with sandbox_review, the supervisor registers that exact card with the native conversation ID. It stays running after the AI finishes. Submitting feedback in the app starts the next turn with that same saved ID. If a turn is still active, feedback waits in the queue so two processes cannot write to the original conversation at once.

The returned session is the conversation's private directory. Use that exact directory to inspect its status or recover a stopped supervisor:

npx -y --package parallelsandbox-mcp@0.5.5 parallelsandbox-agent status --session /the/returned/session-directory
npx -y --package parallelsandbox-mcp@0.5.5 parallelsandbox-agent recover --session /the/returned/session-directory

See native session feedback setup for models, native tool permissions and interrupted turns. Automatic continuation uses explicitly registered native conversations. For an ordinary MCP connection or an already open Desktop conversation that was not registered, press Copy message for AI in the app and paste it into the original conversation to continue.

If the connection does not come up

• The AI tool times out starting ParallelSandbox and shows no error from it. npx is still downloading parallelsandbox-mcp, so the adapter has not started. The newest file in ~/.npm/_logs/ says why. ENETUNREACH or ETIMEDOUT for registry.npmjs.org usually means the computer resolves an IPv6 address it cannot reach: add "NODE_OPTIONS": "--dns-result-order=ipv4first" to the server's env in your AI tool's MCP settings, or install it once with npm i -g parallelsandbox-mcp and run parallelsandbox-mcp instead of npx.
• A tool fails with connection from this computer to ParallelSandbox (…) failed: fetch failed (ENOTFOUND …). This computer could not reach ParallelSandbox (DNS, proxy, VPN, Wi-Fi); the code in parentheses is the reason. It is not the box's network: a box's connections to your environment are in sandbox_status environment.connections[].
• The AI is told goal is required although it never saw a goal field. Its tool list is from before that field: reconnect the MCP server, or restart the AI tool. The adapter also tells the AI tool when the server's tool list changes.
• Calling a sandbox_* tool fails with InputValidationError. Some AI tools load tool schemas only when needed and list the rest as deferred; load them first (Claude Code: ToolSearch).