Execute a shell command in the sandbox.

Args: command: Shell command to run (e.g., "ls -la", "echo hello", "cat /etc/os-release") timeout: Max seconds to wait (default 30) workdir: Working directory inside the sandbox (default /workspace) stdin: Optional input to pipe into the command's stdin sandbox: Named sandbox to use (default "default")

Returns: Command output with stdout, stderr, exit code, and execution time.

Execute Python code in the sandbox (python3 is pre-installed in the default mcp-dev image).

Args: code: Python code to execute. timeout: Max seconds to wait (default 30). sandbox: Named sandbox to use (default "default")

Returns: Script output with stdout, stderr, exit code, and execution time.

Write content to a file in the sandbox.

Args: path: Absolute path in the sandbox (e.g., /workspace/script.py) content: File content to write. sandbox: Named sandbox to use (default "default")

Returns: Confirmation with file path and size.

Read a file from the sandbox.

Args: path: Absolute path to read (e.g., /workspace/output.txt) sandbox: Named sandbox to use (default "default")

Returns: File contents.

Install packages in the sandbox using apk (Alpine package manager).

Args: packages: Space-separated package names (e.g., "python3 nodejs git curl") sandbox: Named sandbox to use (default "default")

Returns: Installation result.

Destroy the current sandbox and create a fresh one. Use this when you want a clean environment.

Args: wipe_workspace: If True, also delete all files in /workspace. If False (default), /workspace files persist across resets. sandbox: Named sandbox to reset (default "default")

Returns: Confirmation of the new sandbox.

Show current sandbox and pool status.

Returns: Status information including active sandboxes, pool size, image, and network.

Quick health check across all sandboxes: shell liveness, disk/memory pressure, uptime. Useful for diagnosing issues when commands fail or sandboxes become unresponsive.

Returns: Per-sandbox health summary with warnings for any issues detected.

Copy a file or directory from the host into the sandbox.

Args: local_path: Absolute path on the host (file or directory). sandbox_path: Destination path inside the sandbox (default: /workspace). sandbox: Named sandbox to use (default "default")

Returns: Confirmation with transferred file count and size.

Copy a file or directory from the sandbox to the host.

Args: sandbox_path: Path inside the sandbox to download. local_path: Absolute destination path on the host. sandbox: Named sandbox to use (default "default")

Returns: Confirmation with transferred size.

Start a background process in the sandbox (e.g., a dev server).

Args: command: Command to run in background (e.g., "python3 -m http.server 8000") name: Optional friendly name for the process (auto-generated if empty) workdir: Working directory (default: /workspace) sandbox: Named sandbox to use (default "default")

Returns: Process ID and name for use with logs/kill.

Read output from a background process.

Args: name: Process name/ID from bg. tail: Number of lines to show from end (default: 50, use 0 for all). sandbox: Named sandbox to use (default "default")

Returns: Process output (stdout + stderr combined).

Kill a background process.

Args: name: Process name/ID from bg. sandbox: Named sandbox to use (default "default")

Returns: Confirmation.

Show resource usage (CPU, memory, disk) of the active sandbox.

Args: sandbox: Named sandbox to check (default "default")

Returns: Current resource usage statistics.

Save the current sandbox state as a reusable snapshot image. The snapshot captures installed packages and system state (not /workspace files, which live on a separate persistent volume).

Args: snapshot_name: Name for the snapshot (e.g., "with-pytorch", "ml-env") sandbox: Named sandbox to snapshot (default "default")

Returns: Confirmation or error.

Destroy the current sandbox and boot from a saved snapshot. Workspace files are preserved (they live on a separate volume).

Args: snapshot_name: Name of the snapshot to restore (from list_snapshots) sandbox: Named sandbox to restore into (default "default")

Returns: Confirmation or error.

List all available sandbox snapshots.

Returns: List of snapshot names, or "none" if no snapshots exist.

Clone a git repository into the sandbox.

Args: repo: Repository URL (e.g., "https://github.com/user/repo.git") branch: Branch to clone (default: repo's default branch) token: Optional auth token for private repos (injected securely, not in URL or history) path: Parent directory for clone (default: /workspace) shallow: If True, clone with --depth 1 for speed (default: True) sandbox: Named sandbox to use (default "default")

Returns: Clone result with repo info.

Start watching a local host directory and live-syncing changes into the sandbox. Does an initial full sync, then polls for changes every second. Ignores .git, node_modules, pycache, .venv, .DS_Store.

Args: local_dir: Absolute path on the host to watch. sandbox_dir: Destination directory in the sandbox (default: /workspace). sandbox: Named sandbox to sync to (default "default")

Returns: Sync job ID and initial sync stats.

Stop a running file sync job.

Args: job_id: The sync job ID from sync_start.

Returns: Confirmation with total files synced.

Manage persistent environment variables in a sandbox. Variables persist across all commands (sourced from /etc/profile.d/mcp-env.sh).

Args: action: "set", "unset", or "list" (default: "list") key: Variable name (required for set/unset) value: Variable value (required for set) sandbox: Named sandbox (default "default")

Returns: Current env vars or confirmation.

Clone a running sandbox to a new name. Copies the full filesystem (except /workspace) to a fresh sandbox. Faster than snapshot+restore since it skips image build.

Args: source: Name of the sandbox to clone from. target: Name for the new cloned sandbox.

Returns: Confirmation with timing.

Show recent command history for a sandbox. Tracks the last 100 commands with exit codes and timing.

Args: limit: Number of recent commands to show (default: 20) sandbox: Named sandbox (default "default")

Returns: Command history with timing and exit codes.

Write multiple files to the sandbox in a single operation. Much faster than multiple write_file calls for scaffolding projects.

Args: files: JSON object mapping absolute paths to file contents. Example: {"/workspace/main.py": "print('hi')", "/workspace/config.yml": "port: 8080"} sandbox: Named sandbox (default "default")

Returns: Confirmation with file count and timing.

List all active sandboxes with their status.

Returns: Table of sandbox names, containers, shell status, and idle time.

Permanently destroy a named sandbox without recreating it. Unlike reset (which destroys and reboots), this just kills it. Workspace volume is preserved and will be reattached if the sandbox is recreated.

Args: sandbox: Name of the sandbox to destroy.

Returns: Confirmation or error.

Delete a saved snapshot image. Frees disk space.

Args: snapshot_name: Name of the snapshot to delete (from list_snapshots).

Returns: Confirmation or error.

Show network information for all sandboxes including IP addresses and pairwise connectivity. Useful for multi-sandbox workflows where services need to communicate.

Returns: Network info with IPs and connectivity status.

Build a container image from a Containerfile (Dockerfile syntax). The image can then be used with restore or as the default image.

Args: name: Name/tag for the built image (e.g., "my-ml-env", "node-app"). containerfile: Containerfile content (Dockerfile syntax). Example: "FROM alpine:3.23\nRUN apk add --no-cache python3"

Returns: Confirmation with build time.

List all available container images (base images + snapshots + custom builds).

Returns: Image listing with names and sizes.

Forward a sandbox port to localhost via TCP proxy. Creates a local listener that proxies connections into the sandbox via container exec.

Args: port: Port number inside the sandbox (e.g., 8000, 3000, 5432). host_port: Port to listen on locally (default: same as sandbox port). sandbox: Named sandbox to expose (default "default").

Returns: Connection URL if successful, or error message.

Stop a port forward previously created by expose.

Args: port: The localhost port to stop forwarding.

Returns: Confirmation with connection stats.

Spawn a child sandbox under a parent sandbox. The parent must have a spawn policy configured in SPAWN_POLICIES. Children have restricted capabilities (no clone/snapshot/restore/reset).

Args: image: Container image for child (default: first allowed image from parent's policy). parent: Name of the parent sandbox (must have spawn policy). name: Name for the child sandbox (auto-generated if empty). cpus: CPU cores for child (0 = use policy default, clamped to policy ceiling). memory: Memory for child e.g. "512M" (empty = use policy default, clamped to ceiling).

Returns: Child sandbox info or error.

List all child sandboxes of a parent.

Args: parent: Name of the parent sandbox.

Returns: List of children with status, or indication that none exist.

Destroy a child sandbox. The child's parent must have a spawn policy.

Args: name: Name of the child sandbox to destroy.

Returns: Confirmation or error.