Create a disposable, isolated environment and copy a project into it.

USE THIS when you are about to do something you should not do on the developer's machine: install dependencies, run a build or a migration, try an upgrade, run unfamiliar code, or explore a fix you are not sure about. Reach for it before the risky step, not after.

The project is SNAPSHOT-COPIED into the sandbox. Files you change inside never propagate back; the developer's working tree is untouched by construction. Secrets (.env files, keys, credential directories) are withheld from the copy, as are node_modules and other build output.

RETURNS an experiment_id plus the isolation actually applied -- read the warnings field, which tells you where your request was clamped.

SAFETY: network is disabled unless you ask for it; no host environment variable is passed unless you name it, and credential-shaped names are refused even then; CPU, memory, PIDs and wall-clock are capped.

Destroy a sandbox and everything in it, returning a final report.

USE THIS as soon as an experiment has told you what you needed. Always call it -- a sandbox left running keeps consuming the developer's CPU and memory.

IDEMPOTENT: calling it on an already-destroyed experiment is safe and returns the stored report rather than an error.

RETURNS the final report, including what changed inside the sandbox, so you can summarise the experiment after it is gone.

Run a shell command inside a sandbox.

USE THIS for anything you would otherwise run in the developer's terminal: installs, builds, scripts, migrations, one-off exploration. The command runs in the container, never on the host.

RETURNS exit code, stdout, stderr and duration. A non-zero exit is a normal result, not an error -- read it and decide what to try next.

Set background=true for something long-running, then poll get_job_status and fetch get_job_result when it finishes. Otherwise this waits, bounded by the timeout, so it cannot hang your session.

Run the project's test suite inside a sandbox and parse the results.

USE THIS instead of execute_experiment when you want to know whether the project still works -- it detects the runner (npm, pytest, cargo, go, make) by looking at what is actually in the sandbox, and parses counts out of the output.

RETURNS exit code, stdout/stderr, duration and, when parseable, a summary with passed/failed/total and the names of failing tests. If test_summary.detected is false, trust the exit code, not the zeros.

Pass command to override detection.

Read a file from inside the sandbox as text.

USE THIS to investigate a failure -- read the source, the config, a log -- without guessing from stack traces. Paths are workspace-relative and cannot escape it; this tool cannot read the developer's machine.

Write a file inside the sandbox, creating parent directories as needed.

USE THIS to apply a candidate fix. Prefer it over shell heredocs: no quoting to get wrong.

SAFETY: writes land in the sandbox copy only. There is no tool here that writes to the developer's project -- if a change is worth keeping, show them the diff from inspect_changes and let them apply it.

Show what the experiment changed, against the project as it was copied in.

USE THIS before destroying a sandbox, and before telling the developer what you found. It is the evidence for your conclusion.

RETURNS created / modified / deleted file lists plus insertion and deletion counts, and optionally the unified diff. Build output and dependency directories are excluded, so a 30,000-file node_modules will not bury the two lines that matter.

Copy selected files out of a sandbox before it is destroyed.

USE THIS for build output, test reports, coverage, benchmark results or logs you want to keep or quote.

Patterns are workspace-relative shell globs ('dist/*.js'), or '/name' for a recursive search ('/junit.xml'). Files land in the server's own state directory; this tool cannot write anywhere on the developer's machine.

Fetch an experiment's full state and a summary of what happened in it.

USE THIS to re-orient -- after a long gap, or to check whether a sandbox is still alive before sending more commands.

RETURNS status, base image, isolation settings, resource limits, how many commands ran and how many failed, the last test summary, change statistics and artifact count.

List experiments, most recent first.

USE THIS to find a sandbox you created earlier, or to check for ones you forgot to destroy before creating another.

Check on a command started with background=true.

RETURNS status and elapsed milliseconds. Poll this, then call get_job_result once finished is true.

Fetch the completed result of a background command.

RETURNS the same shape as execute_experiment: exit code, stdout, stderr, duration. If the job is still running this waits for it, bounded by the job's own timeout.

Stop a running command and kill its process inside the sandbox.

USE THIS when a command is clearly stuck or no longer needed. Safe on a job that already finished -- it returns the final state untouched.

Compare two or more experiments side by side.

USE THIS when you tried several approaches -- three candidate fixes, two runtime versions, a couple of dependency upgrades -- and have to recommend one. Run each approach in its own experiment, then compare.

RETURNS per-experiment test results, failing test names, exit codes, change size, duration and artifact counts, plus a recommendation when the evidence supports one. Destroyed experiments are still comparable: their findings were recorded before teardown.

Confirm the sandbox runtime is available and report the active defaults.

USE THIS first if create_experiment fails, to tell a stopped Docker daemon apart from a rejected request. Returns the Docker version the server is talking to and the isolation defaults every experiment starts from.