Sandboxer

Create a cloud sandbox (an Ubuntu microVM with root, Docker, git, Node and Python) and wait until it is ready. Returns its id and URL; later calls use it by default. Start from a named snapshot with from (a name, or a versioned name for its newest version) or fromLabels (the newest snapshot with all those labels).

List your sandboxes with their state, URL and labels.

Show one sandbox: state, URL, when it stops automatically, labels and stored bytes.

Run a shell command (bash -c) in the sandbox. By default it waits and returns stdout, stderr and the exit code (timeoutSeconds, default 120, max 600). With detached: true it starts the command in the background and returns its processId at once: read its output and exit code with command_status, stop it with kill_command. Use detached for anything long (builds, test suites, servers).

Status of a detached command: running or its exit code, and its output. Pass the stdoutOffset/stderrOffset from the previous call to get only new output.

Stop a detached command.

Read a file from the sandbox (up to 5 MiB).

Create or overwrite a file in the sandbox (up to 5 MiB). Parent directories are created.

Serve a port of the sandbox on a stable public HTTPS URL. The URL carries an access token unless public is true. Start the service first, listening on 0.0.0.0 (or set localhost).

Snapshot the sandbox (memory included) and stop billing. Files, installed packages and running processes are kept; resume_sandbox brings it back.

Resume a stopped sandbox from its snapshot and wait until it is ready. Its memory (running processes) is restored when a machine of its CPU type is free within 2 minutes; otherwise it boots from disk (files intact) and the result says so. requireMemory: true waits up to 30 minutes for its memory instead and fails rather than boot from disk.

Set when the sandbox stops: ttlSeconds from now (0 never), and/or idleStopMinutes (pause after that long without activity, waking on use; 0 never).

Change the sandbox's display name.

Replace the sandbox's labels ({} clears them).

Delete a sandbox permanently: its disk, memory and automatic snapshots go (named snapshots saved from it stay). sandboxId is required: there is no default and no wildcard.

Save the sandbox as a named snapshot to create new sandboxes from, and wait until it is saved. With versioned: true each save is a new version (<name>-v<N>); ifLatest saves only if the newest version is still that number (safe concurrent saves); keep deletes all but the newest N versions.

List your named snapshots: name, version, labels, created time, stored bytes (what counts toward your storage) and disk size (logical).

Delete one named snapshot (one version, e.g. ci-base-v3). name is required: there is no wildcard.