Create Experiment
create_experimentRun risky commands in a disposable, isolated Docker sandbox with a snapshot copy of your project, keeping your host untouched. Test builds, installs, and migrations safely with enforced limits.
Instructions
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| timeout | No | Default per-command wall-clock limit in seconds. | |
| cpu_limit | No | CPU cores. Clamped. | |
| objective | No | What you are trying to find out. Shows up in the report. | |
| base_image | No | Docker image to run in, e.g. 'node:22-slim', 'python:3.12-slim'. Choose the runtime the experiment is actually about. | |
| memory_limit | No | Memory, e.g. '2GB'. Clamped. | |
| network_mode | No | 'none' (default, no network at all), 'restricted' (egress on a private bridge, no reach to other sandboxes), or 'enabled'. Use 'restricted' when you must install packages. | |
| project_path | No | Absolute path to the project to copy in. Omit for an empty sandbox. Must not be a home or system directory. | |
| mount_strategy | No | 'COPY_TO_SANDBOX' (default, safest) or 'READ_ONLY_BIND_MOUNT' for a large repo you only need to read. Writable host mounts do not exist. | |
| setup_commands | No | Commands to run once the sandbox is ready, in order. Stops at the first failure and reports it. | |
| environment_allowlist | No | Environment variables to expose. 'NAME' forwards the host's value; 'NAME=value' injects a literal. Nothing else crosses the boundary. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | ||
| warnings | No | ||
| base_image | Yes | ||
| setup_jobs | No | ||
| files_copied | No | ||
| network_mode | Yes | How much of the network the sandbox can see. ``NONE`` -- no interfaces at all. The default. ``RESTRICTED`` -- an isolated bridge network shared by nothing else; egress works, but the sandbox cannot reach other sandboxes or the host's service ports. ``ENABLED`` -- the daemon's default bridge. Full egress. | |
| project_name | Yes | ||
| experiment_id | Yes | ||
| mount_strategy | Yes | How the project reaches the sandbox. ``COPY_TO_SANDBOX`` -- snapshot the tree, hand the copy to the container. The host tree is unreachable. ``READ_ONLY_BIND_MOUNT`` -- bind the real tree read-only. Faster on large repos; writes to it fail by construction. | |
| workspace_path | Yes | ||
| resource_limits | Yes | ||
| environment_passed | No |