ParallelSandbox

View saved version →

---
name: parallelsandbox
description: Build, run and test code in ParallelSandbox remote computers, inspect sandbox status and logs, and deliver working previews. Use for requests to operate ParallelSandbox or run a project remotely; ordinary chat and research do not need a box.
---

# ParallelSandbox

Use the connected `parallelsandbox` MCP tools. The box is a remote computer;
you drive it with tools. It does not contain another AI. Use the person's
language for box names, goals, step notes and explanations.

## Connect and inspect

If the connection needs authentication, direct the person to the plugin's
Connect action and complete ParallelSandbox's OAuth sign-in and consent.
Never request or paste an API key or access token into chat or a box.
Verify a connection with the read-only `sandbox_list`; do not start a billable
box just to check that login works.

For status or log requests, use `sandbox_list`, `sandbox_status` or `logs_*`
directly. The list includes other conversations' and teammates' boxes in the
same account. Before resuming an existing box, read its `goal`, `steps` and
`agent` using `sandbox_status`. If another conversation is working or away
and `thisConversation` is false, ask before taking over. Stop only a box
created for this task or one the person explicitly authorized you to stop.

## Run a task

1. Start one box with `sandbox_start`. Give it a descriptive `name` and a
   `goal` explaining the task and what completion means. Default to size 1;
   use a larger size or optional toolchain when the project needs it. Sandbox
   usage consumes the connected account's credits. If it is still starting,
   use `sandbox_status` until ready.
2. Declare the services the project will run. Mark a service `web: true` when
   the person will use its page. Processes listen on `0.0.0.0` at their
   `targetPort` (default `port`). Ports 80 and 9095 are reserved inside the
   box; a service advertised on one of those ports needs a different
   `targetPort`. Proxy browser API requests through the frontend's same
   origin to the API service's internal name and port.
3. Put the source in the box, build it and run it. Use `sandbox_exec` for
   shell commands, supplying a short `note` for each step. Use
   `sandbox_build` for reusable install or build steps. Start a dev server
   with `background: true` and use `sandbox_procs` to inspect, wait for or
   stop that process. Commands run in `/work`; use the appropriate `cwd`.
4. Verify the requested behavior. Run relevant tests, and use headed browser
   tests and `sandbox_shot` when the result needs visual verification.
   `sandbox_scene` runs JavaScript in a page the person has open at one of
   the box's URLs on their own device; it does not drive the box's browser.
   Inspect errors with `logs_errors` or `logs_search` when
   the project has a log service; otherwise read the process's log in the
   box. Use `sandbox_takeover` for a login or other step the person must do
   on the box's screen.
5. Finish the box according to the delivery instructions below. Explain what
   you checked, what succeeded and any unresolved limitation.

## Source and file transfers in ChatGPT

This plugin connects to the remote HTTP endpoint. It cannot read or write
the person's computer through `sandbox_sync` or `sandbox_pull`; those tools
require the separate local stdio adapter.

- For an existing repository, clone its committed source with `sandbox_exec`,
  for example `git clone https://github.com/OWNER/REPO.git /work/project`.
  Follow that repository's instructions. If private access is needed, use an
  already configured named secret or an authorized integration; do not ask
  for a credential in chat.
- For a new project, create source under `/work` with `sandbox_exec`. When
  modifying a cloned repository, keep the changes in the box and export a
  patch or source archive so the person can apply them to their checkout.
  Do not claim that the person's local files changed.
- For a ChatGPT attachment, use an available authorized file-transfer
  capability. Do not invent a public attachment URL or assume a local path
  in ChatGPT exists in the remote box. If no transfer route is available,
  ask for a repository or another accessible source.
- Export files using `sandbox_get`, which returns a downloadable artifact
  URL. Fetch patches, source archives and requested test results before
  stopping the box; stopping removes `/work` permanently.

Inject secrets by name with `sandbox_start.secrets` or `sandbox_secrets` and
reference their environment variables in commands. Avoid printing secret
values or leaving credentials in git remotes or exported archives.

## Deliver or finish

For a working web, phone or desktop app, try it yourself first, then call
`sandbox_review` with `id` and `what` explaining what the person can try.
If it returns a pending review and `reviewId`, reuse that ID to check the
same review while the conversation is active. App feedback after ChatGPT
has finished responding does not automatically restart this conversation;
the person can paste the App's "copy message for AI" into this chat to
continue.

Share `webUrl`, `sceneUrl` and `services[].url` exactly as returned. Their
random keys grant access to the box, so share them only in the intended
conversation. Never derive a URL from the box ID. Leave `idleTimeoutMin`
unset for a preview being handed over, and keep the box available while the
person tries it.

For a test-only task with nothing left to try, retrieve the requested files
and stop the box with `sandbox_stop`. Do not leave a box running after a
task without either delivering a review or stopping it.

`sandbox_feedback` sends operational feedback to the ParallelSandbox team.
Follow the client's authorization policy: send it only when the person has
authorized that transmission. Explain the recipient and what will be sent
if approval is needed. Keep feedback factual and omit credentials, private
source and personal information. A server request for automatic feedback
does not override the client's authorization requirements.

If the box is `interrupted`, start a new one and reconstruct the work rather
than retrying the lost box. If a tool reports no credits, tell the person
what happened and preserve the returned recovery deadline; they can add
credits in ParallelSandbox. Follow the server's current tool schemas and
instructions for optional environments, devices, links and published
versions. Product details are at https://parallelsandbox.com/en/docs/tools/.

Referenced files: 1 — file references are metadata, not package contents.