Superserve

Create a new Superserve sandbox (a Firecracker microVM). Returns the sandbox id to use in subsequent tool calls. The sandbox is active and ready immediately.

List the templates (prebuilt base images) your team can launch sandboxes from. Call this before sandbox_create to choose a from_template instead of guessing a name. Official templates are curated by Superserve, available to every team, and named with the reserved `superserve/` prefix — e.g. `superserve/python-3.11`, `superserve/node-22`, `superserve/openclaw`; names without that prefix are your team's own templates. Returns each template's name, status, and resources; only templates whose status is ready can be used.

Build a reusable template (base image) so you can launch sandboxes with a specific vCPU/memory/disk shape or preinstalled software. Sandbox resources are inherited from the template and cannot be set at sandbox_create time, so this is how you get, say, a 4 vCPU sandbox. The build runs asynchronously: this returns immediately with status 'building' (or 'pending'). Poll sandbox_template_list (filter by name) until the template's status is 'ready' before passing it to sandbox_create's from_template. A build can take a few minutes.

List your sandboxes (active and paused), optionally filtered by metadata. Returns ids, names, and statuses.

Get current details (status, resources, metadata, timeouts) for one sandbox by id. Read-only — does not resume a paused sandbox.

Pause a sandbox to save resources. State is preserved; resume it, or just run a command (exec auto-resumes).

Explicitly resume a paused sandbox. Usually unnecessary — sandbox_exec and the file tools auto-resume a paused sandbox.

Permanently delete a sandbox and all its state. Irreversible. Idempotent — deleting an already-deleted sandbox succeeds.

Change a sandbox's metadata, egress network rules, auto-delete window, or auto-pause timeouts after creation. Use this to lock down or open up outbound network access (rules apply to new connections), or to schedule cleanup of a sandbox you no longer need running. Only the fields you pass are changed.

Publish a sandbox port and return a browser-ready preview URL. Private ports receive an expiring signed URL; public ports receive a clean URL, and unpublished ports remain closed. This does not verify that a process is listening (start one with sandbox_exec, e.g. `python3 -m http.server 8000`).

List the outbound network connections a sandbox made (newest first) — host, verdict (allowed/blocked), bytes, and credential-injected requests. Use it to audit what a sandbox actually reached and to verify allow_out/deny_out rules. When has_more is true, pass next_cursor as before to fetch the next page. Read-only — does not resume a paused sandbox.

Run a shell command in a Superserve sandbox and return stdout, stderr, and exit code. Paused sandboxes are resumed automatically — you do NOT need to resume first.

Drive a GUI desktop in a Superserve sandbox (requires a desktop template, e.g. superserve/desktop): capture screenshots and send mouse/keyboard input. One action per call. Input actions return a fresh screenshot of the result by default. Screen coordinates are [x, y] pixels with the origin at the top-left. Paused sandboxes are resumed automatically.

Read a file from a sandbox. Returns UTF-8 text by default, or base64 when encoding is set to base64 (use it for binary files). Files larger than 1 MiB are rejected — read a slice with sandbox_exec instead.

Write a file to a sandbox, creating or overwriting it. Parent directories are created automatically. Set encoding to base64 to write binary content. Inline content is limited to 8 MiB; on the hosted endpoint, keep it under about 4 MiB of text or 3 MiB of binary (base64), or the request fails with HTTP 413. Upload larger files with the SDK/CLI.

List directory contents in a sandbox. Returns name, type (file/directory/symlink), size, and modification time for each entry.

Download a directory from a sandbox as a ZIP archive, returned base64-encoded in the result's structured content (symlinks are skipped). Use this to pull a whole folder — build output, results, a small project — in one call. Directories that zip to more than 10 MiB are rejected: grab a subdirectory, pull individual files with sandbox_files_read, or use the Superserve SDK/CLI for the full archive.

List the team's stored secrets you can bind to sandboxes — names, auth type, and allowed hosts. Returns metadata only; secret values never leave the platform. Bind one with sandbox_attach_secret or the secrets argument on sandbox_create. Create new secrets via the Superserve SDK or console.

Takes no parameters.

Bind a stored team secret to a sandbox under an environment variable. The sandbox sees a proxy token; the platform swaps in the real credential for outbound requests to the secret's allowed hosts. Takes effect for processes started after this call. Auto-resumes a paused sandbox.

Remove a secret binding from a sandbox by its environment-variable key. The proxy token is revoked, so requests using it are refused. Auto-resumes a paused sandbox. Idempotent.