# Superserve - [Introduction](https://docs.superserve.ai/introduction.md): Superserve provides sandbox infrastructure to run code in isolated cloud environments powered by Firecracker MicroVMs. - [Quickstart](https://docs.superserve.ai/quickstart.md): Create your first sandbox, run a command, and read a file. - [Get an API key](https://docs.superserve.ai/api-key.md): Create an API key and configure the SDK to authenticate with Superserve. - [Create a sandbox](https://docs.superserve.ai/sandbox/create.md): Spin up an isolated Firecracker MicroVM in seconds, ready to run commands immediately. - [Connect to an existing sandbox](https://docs.superserve.ai/sandbox/connect.md): Reconnect to a sandbox you created earlier using its ID, and list sandboxes on your team. - [Pause, resume, and delete](https://docs.superserve.ai/sandbox/lifecycle.md): Manage sandbox state - pause to save compute costs, resume on demand, delete when you're done. - [Metadata tags](https://docs.superserve.ai/sandbox/metadata.md): Attach string key-value tags to sandboxes, update them later, and filter sandboxes by tag. - [Network rules](https://docs.superserve.ai/sandbox/networking.md): Lock down sandbox egress to specific CIDRs or domains with allow and deny lists. - [Preview URLs](https://docs.superserve.ai/sandbox/preview-urls.md): Publish sandbox ports with public access or per-port authentication. - [Network log](https://docs.superserve.ai/sandbox/network-log.md): See every HTTP and HTTPS connection a sandbox made to a public address on ports 80 and 443 — allowed, blocked, or failed — and every secret-bearing request, in one timeline. - [Environment variables](https://docs.superserve.ai/sandbox/environment-variables.md): Inject environment variables at sandbox creation - applied to every process spawned inside the VM. - [Secrets](https://docs.superserve.ai/secrets/overview.md): Give a sandbox an API key without the key ever entering the sandbox. The platform attaches your real credential to outbound requests. - [Create a secret](https://docs.superserve.ai/secrets/create.md): Store a credential with a provider shortcut or a custom auth scheme, then rotate or delete it without touching your sandboxes. - [Bind secrets to a sandbox](https://docs.superserve.ai/secrets/binding.md): Map secrets to environment variables at sandbox creation. Code in the sandbox reads the env var; the platform attaches the real value to outbound requests. - [Audit secret usage](https://docs.superserve.ai/secrets/audit.md): See every request made with a secret — across all sandboxes — and which sandboxes a secret is bound to. - [Templates](https://docs.superserve.ai/templates/overview.md): Reusable base images with build steps that sandboxes boot from - [Create a template](https://docs.superserve.ai/templates/create.md): Build your first team template, stream logs, launch a sandbox from it - [Rebuild, cancel, delete](https://docs.superserve.ai/templates/lifecycle.md): Manage a template over time: trigger new builds, cancel in-flight ones, delete stale templates - [BuildSpec reference](https://docs.superserve.ai/templates/build-spec.md): How to describe a template's base image, build steps, and runtime defaults - [Run commands in a sandbox](https://docs.superserve.ai/commands/overview.md): Execute shell commands inside a sandbox with sync or streaming output. - [Stream command output](https://docs.superserve.ai/commands/streaming.md): Watch a command's stdout and stderr as it runs. - [Interactive processes](https://docs.superserve.ai/commands/sessions.md): Send input to a running command, signal it, and stream its output back. - [Read and write files](https://docs.superserve.ai/filesystem/read-write.md): Upload and download files to and from a sandbox's filesystem. - [Mesa](https://docs.superserve.ai/storage/mesa.md): Mount Mesa versioned virtual filesystems inside a Superserve sandbox to persist and branch agent workspaces across runs. - [Archil](https://docs.superserve.ai/storage/archil.md): Mount an Archil elastic filesystem in a Superserve sandbox to share and persist workspaces, caches, and datasets across runs. - [Cloud buckets](https://docs.superserve.ai/storage/cloud-buckets.md): Mount an S3, GCS, or R2 bucket inside a Superserve sandbox with a FUSE driver to read and write object storage as ordinary files. - [Errors](https://docs.superserve.ai/errors.md): Typed errors thrown by the Superserve SDK and when to catch each one. - [Sandbox](https://docs.superserve.ai/sdk-reference/sandbox.md): The Sandbox class - factory methods, sandbox methods, properties, and types. - [Secret](https://docs.superserve.ai/sdk-reference/secret.md): The Secret and Provider classes - factory methods, instance methods, and types for credential management. - [Template](https://docs.superserve.ai/sdk-reference/template.md): The Template class - factory methods, instance methods, properties, and types. - [Commands](https://docs.superserve.ai/sdk-reference/commands.md): Run shell commands in a sandbox, one-shot or as an interactive session. - [Files](https://docs.superserve.ai/sdk-reference/files.md): sandbox.files - read and write files inside a sandbox's filesystem. - [List all sandboxes](https://docs.superserve.ai/api-reference/sandboxes/list-all-sandboxes.md): Returns sandboxes belonging to the authenticated team, ordered by creation time (newest first) by default. - [Create a new sandbox](https://docs.superserve.ai/api-reference/sandboxes/create-a-new-sandbox.md): Creates a sandbox from a template (defaults to `superserve/base` when `from_template` is omitted). When the request returns successfully, the sandbox is ready to use — you can run commands against it immediately. - [Get a sandbox by ID](https://docs.superserve.ai/api-reference/sandboxes/get-a-sandbox-by-id.md) - [Partially update a running sandbox](https://docs.superserve.ai/api-reference/sandboxes/partially-update-a-running-sandbox.md): Applies a partial update to a running sandbox. Each top-level field in the request body is optional; only fields that are present are applied. Omitted top-level fields are left unchanged. Nested objects are full replacements when present — to clear a list, send it as an empty array. - [Delete a sandbox](https://docs.superserve.ai/api-reference/sandboxes/delete-a-sandbox.md) - [Pause a running sandbox](https://docs.superserve.ai/api-reference/sandboxes/pause-a-running-sandbox.md): Snapshots the sandbox's full state (memory + disk), suspends the VM, and transitions to `paused`. Resume it later to continue exactly where it left off — same memory, same running processes, same files. - [Resume a paused sandbox](https://docs.superserve.ai/api-reference/sandboxes/resume-a-paused-sandbox.md): Restores the sandbox from its paused snapshot. Transitions back to `active` with all state intact — same memory, same processes, same files. - [Activate a sandbox](https://docs.superserve.ai/api-reference/sandboxes/activate-a-sandbox.md): Returns the sandbox with a fresh access token. If the sandbox is paused, it is resumed first. Idempotent — calling it on an active sandbox just returns a new token. - [List a sandbox's egress activity](https://docs.superserve.ai/api-reference/sandboxes/list-a-sandboxs-egress-activity.md): The unified per-sandbox network log: every outbound connection the sandbox made, merged into one time-ordered stream, most recent first. Each row has a `kind` — `connection` (host, bytes, allow/deny verdict) or `request` (HTTP method, path, status, and the secret used, when a credential was injected… - [List published preview ports](https://docs.superserve.ai/api-reference/sandboxes/list-published-preview-ports.md): Returns the sandbox's preview routing mode and its published ports. For a strict `public` or `private` sandbox, only the ports listed here are published at `https://{port}-{sandbox_id}.`; every other numeric port returns 404. Each row reports its independent access mode. Private port… - [Publish or update a preview port](https://docs.superserve.ai/api-reference/sandboxes/publish-or-update-a-preview-port.md): Adds a port to the sandbox's published set, optionally with an explicit `public` or `private` mode. On a new row, omitted `access` inherits the sandbox's current `preview_access` default. On an existing row, omitted `access` preserves that row's current mode; only an explicit value changes it. An ex… - [Unpublish a preview port](https://docs.superserve.ai/api-reference/sandboxes/unpublish-a-preview-port.md): Removes a port from the published set. On a strict sandbox, the port immediately returns 404 at the edge. - [Mint a token for a private preview port](https://docs.superserve.ai/api-reference/sandboxes/mint-a-token-for-a-private-preview-port.md): Activates token authentication for an already-published private port and returns a credential scoped to exactly this sandbox, port, and token generation. A machine client sends the response's `token` value in a request header whose name is the response's `header` value. - [Rotate a private preview port's token generation](https://docs.superserve.ai/api-reference/sandboxes/rotate-a-private-preview-ports-token-generation.md): Advances only this published private port's token generation, revoking every older token for it while leaving sibling ports unchanged. The revocation is committed even if the current host cannot deliver or enforce the replacement; in that case the request returns an error and no credential. Rotation… - [Run a command and wait for it to finish](https://docs.superserve.ai/api-reference/exec/run-a-command-and-wait-for-it-to-finish.md): Runs a command to completion and returns its output in a single response, retained up to a server-side cap (see `truncated`). For live or unbounded output use `POST /exec/stream` (Server-Sent Events) or `GET /exec/connect` (WebSocket). A non-zero exit code is returned in the body, not as an HTTP err… - [Run a command and stream output over SSE](https://docs.superserve.ai/api-reference/exec/run-a-command-and-stream-output-over-sse.md): Runs a command and streams its output as Server-Sent Events while it runs. Each `data:` line is a JSON object: an output chunk (`{"stdout":"..."}` or `{"stderr":"..."}`), the terminal event (`{"exit_code":N,"finished":true}`), or an error (`{"error":"...","finished":true}`). The stream closes when t… - [Run a command over a WebSocket](https://docs.superserve.ai/api-reference/exec/run-a-command-over-a-websocket.md): Runs a command over a WebSocket, streaming output back and accepting stdin over one connection. - [List a directory inside a sandbox](https://docs.superserve.ai/api-reference/files/list-a-directory-inside-a-sandbox.md): Returns a one-level listing of a directory inside the sandbox. The listing is served through the control plane, so it works on every sandbox regardless of when it was created. A paused sandbox is resumed automatically before the listing and stays active afterward. `modified_unix` is 0 for entries on… - [Read a file from a sandbox](https://docs.superserve.ai/api-reference/files/read-a-file-from-a-sandbox.md): Returns the file at `path` as raw bytes. To download a directory, set `format=zip` to receive its contents as a zip archive. - [Write a file to a sandbox](https://docs.superserve.ai/api-reference/files/write-a-file-to-a-sandbox.md): Creates parent directories as needed and overwrites any existing file. - [List templates visible to the caller](https://docs.superserve.ai/api-reference/templates/list-templates-visible-to-the-caller.md): Returns the caller's team's templates plus the curated system templates (available to everyone, identified by the `superserve/` name prefix — e.g. `superserve/base`, `superserve/python-3.11`, `superserve/node-22`), ordered by creation time (newest first) by default. - [Create a template and kick off the first build](https://docs.superserve.ai/api-reference/templates/create-a-template-and-kick-off-the-first-build.md): Creates a template and queues the first build. The response includes both the template id and the build id, so clients can immediately poll `GET /templates/{id}` for overall status or subscribe to `GET /templates/{id}/builds/{build_id}/logs` for live output. - [Get a template by ID](https://docs.superserve.ai/api-reference/templates/get-a-template-by-id.md) - [Delete a template](https://docs.superserve.ai/api-reference/templates/delete-a-template.md): Delete a template owned by the caller's team. Returns `409` if any active or paused sandbox still references this template, or if a build is currently in progress; cancel those first. - [List recent builds for a template](https://docs.superserve.ai/api-reference/templates/list-recent-builds-for-a-template.md) - [Rebuild an existing template](https://docs.superserve.ai/api-reference/templates/rebuild-an-existing-template.md): Queues a new build for this template. Used to retry after a failed build, or to rebuild when the base image has been updated. - [Get a build by ID](https://docs.superserve.ai/api-reference/templates/get-a-build-by-id.md) - [Cancel an in-flight build](https://docs.superserve.ai/api-reference/templates/cancel-an-in-flight-build.md): Cancels an in-flight build. No-op for builds already in a terminal state. - [Stream build logs via SSE](https://docs.superserve.ai/api-reference/templates/stream-build-logs-via-sse.md): Server-Sent Events stream of the build's stdout/stderr. Connecting replays buffered output from the start of the build, then streams live as it arrives. Closes when the build reaches a terminal state. - [Create a secret](https://docs.superserve.ai/api-reference/secrets/create-a-secret.md): Stores a credential under the caller's team. The plaintext is envelope-encrypted at rest and is never returned by any API. At sandbox-create time, bind the secret to an environment-variable name via the `secrets` map on `POST /sandboxes`; the agent sees a proxy token in env and the in-host enforceme… - [List secrets for the calling team](https://docs.superserve.ai/api-reference/secrets/list-secrets-for-the-calling-team.md): Returns metadata for all secrets owned by the team. Cleartext values are never returned. - [Get a secret's metadata](https://docs.superserve.ai/api-reference/secrets/get-a-secrets-metadata.md): Returns metadata only — the cleartext value is never returned. - [Rotate a secret's value](https://docs.superserve.ai/api-reference/secrets/rotate-a-secrets-value.md): Replaces the stored ciphertext with a freshly-encrypted copy of the new value. All sandboxes bound to this secret continue to work; in-host caches are invalidated so the next egress uses the new value. - [Revoke a secret](https://docs.superserve.ai/api-reference/secrets/revoke-a-secret.md): Soft-deletes the secret: the proxy daemon refuses to serve it and new sandbox bindings fail. Existing audit-history queries still resolve the row. The same name can be re-used by creating a new secret. - [Attach a secret to a sandbox](https://docs.superserve.ai/api-reference/sandboxes/attach-a-secret-to-a-sandbox.md): Binds a stored secret to an existing sandbox under an env var. The sandbox sees a stand-in token; the credential is swapped in for outbound requests to its allowed hosts. Takes effect for processes started after this call; a paused sandbox applies it on resume. - [Detach a secret from a sandbox](https://docs.superserve.ai/api-reference/sandboxes/detach-a-secret-from-a-sandbox.md): Removes a secret binding from an existing sandbox and revokes its stand-in token, so requests that use it are refused — for an already-running process, within about a minute. A paused sandbox applies the change on resume. - [List proxy egress events that used this credential](https://docs.superserve.ai/api-reference/secrets/list-proxy-egress-events-that-used-this-credential.md): Returns proxy_audit events for every outbound request that the in-host enforcement daemon swapped with this credential, across every sandbox it was bound to. Each row includes the originating sandbox name (null when that sandbox has since been deleted). - [List sandboxes currently bound to this credential](https://docs.superserve.ai/api-reference/secrets/list-sandboxes-currently-bound-to-this-credential.md): Returns the active (non-destroyed) sandboxes that have this credential bound, with the env-var name each binding uses. Useful before rotation or deletion ("which sandboxes will be affected?"). - [List the built-in provider shortcut catalog](https://docs.superserve.ai/api-reference/secrets/list-the-built-in-provider-shortcut-catalog.md): Returns the providers customers can pass as `provider` on `POST /secrets`. Backend-of-record so the console picker stays in sync as the catalog grows. - [Get billing pricing](https://docs.superserve.ai/api-reference/billing/get-billing-pricing.md): Returns the authenticated team's active pricing plan and current resource rates for billing UI display. The team is derived from authentication; callers cannot select a team by query parameter. - [Get public PAYG billing pricing](https://docs.superserve.ai/api-reference/billing/get-public-payg-billing-pricing.md): Returns the active public pay-as-you-go pricing plan and current resource rates. This endpoint is unauthenticated so public pricing pages can render from the same pricing data used by billing. - [Get billing summary](https://docs.superserve.ai/api-reference/billing/get-billing-summary.md): Returns team-level financial information for the authenticated team's current billing period. All charge fields are monetary USD values, not raw usage metrics. The team is derived from authentication; callers cannot select a team by query parameter. - [Get timezone-aware billing usage chart buckets](https://docs.superserve.ai/api-reference/billing/get-timezone-aware-billing-usage-chart-buckets.md): Returns zero-filled local-calendar buckets for the half-open [start,end) range. `timezone` must be an IANA timezone name (for example, `America/Chicago`). The response is limited to 400 buckets. Every request requires the authenticated team's `billing:read` permission. `billed_total_usd` is gross CP… - [List team billing periods](https://docs.superserve.ai/api-reference/billing/list-team-billing-periods.md): Lists persisted billing periods for the specified team. Customer callers may only access their own team and must hold `billing:read`. - [Preview team billing export payload](https://docs.superserve.ai/api-reference/billing/preview-team-billing-export-payload.md) - [Get team billing usage](https://docs.superserve.ai/api-reference/billing/get-team-billing-usage.md): Returns billing usage for the specified team and billing period. Customer callers may only access their own team and must hold `billing:read`. - [Create a Stripe Checkout session](https://docs.superserve.ai/api-reference/billing/create-a-stripe-checkout-session.md) - [Create a Stripe customer portal session](https://docs.superserve.ai/api-reference/billing/create-a-stripe-customer-portal-session.md) - [Receive Stripe webhooks](https://docs.superserve.ai/api-reference/billing/receive-stripe-webhooks.md): Stripe webhook receiver. Requests are authenticated with the Stripe signature header instead of an API key. - [Get team management state](https://docs.superserve.ai/api-reference/rbac/get-team-management-state.md): Returns the caller-visible team members, role assignments, and capability flags used by customer-facing member management UI. The authenticated API key determines the actor; customer clients must not send or rely on `X-Actor-User-Id`. - [List team members](https://docs.superserve.ai/api-reference/rbac/list-team-members.md) - [Add or invite a team member](https://docs.superserve.ai/api-reference/rbac/add-or-invite-a-team-member.md) - [Deactivate a team member](https://docs.superserve.ai/api-reference/rbac/deactivate-a-team-member.md) - [List team role assignments](https://docs.superserve.ai/api-reference/rbac/list-team-role-assignments.md) - [Assign a team role](https://docs.superserve.ai/api-reference/rbac/assign-a-team-role.md) - [Revoke a team role](https://docs.superserve.ai/api-reference/rbac/revoke-a-team-role.md) - [List team audit-log activity](https://docs.superserve.ai/api-reference/activity/list-team-audit-log-activity.md): Returns audit-log activity for the authenticated team, ordered by creation time (newest first) by default. Backs the console Audit Logs page. - [Claude Code](https://docs.superserve.ai/integrations/coding-agents/claude.md): Run Claude Code in a Superserve sandbox. - [Codex](https://docs.superserve.ai/integrations/coding-agents/codex.md): Run the OpenAI Codex CLI in a Superserve sandbox. - [Opencode](https://docs.superserve.ai/integrations/coding-agents/opencode.md): Run Opencode in a Superserve sandbox. - [Kilocode](https://docs.superserve.ai/integrations/coding-agents/kilocode.md): Run Kilocode in a Superserve sandbox. - [OpenClaw](https://docs.superserve.ai/integrations/personal-agents/openclaw.md): Run OpenClaw in a Superserve sandbox. - [Hermes](https://docs.superserve.ai/integrations/personal-agents/hermes.md): Run the Hermes agent in a Superserve sandbox. - [Run Claude Managed Agents on Superserve](https://docs.superserve.ai/integrations/managed-agents/claude-managed-agents.md): A guide to running Claude Managed Agents inside your own Superserve sandboxes, as a self-hosted environment. - [Run Cursor Self-Hosted Machines on Superserve](https://docs.superserve.ai/integrations/managed-agents/cursor-cloud-agents.md): Get the control of Cursor Self-Hosted Machines without having to manage a fleet of machines. Every Cloud Agent gets its own Superserve sandbox, built from your image, deleted or paused when it's done. - [Agno](https://docs.superserve.ai/integrations/agent-harnesses/agno.md): Run code from Agno agents in isolated Superserve sandboxes with SuperserveTools. - [Claude Agent SDK](https://docs.superserve.ai/integrations/agent-harnesses/claude-agent-sdk.md): Use Superserve sandboxes as the execution runtime for agents built with the Claude Agent SDK. - [LangChain](https://docs.superserve.ai/integrations/agent-harnesses/langchain.md): Run Deep Agents, LangGraph, and LangChain agents in isolated Superserve sandboxes with langchain-superserve. - [OpenAI Agents SDK](https://docs.superserve.ai/integrations/agent-harnesses/openai-agents-sdk.md): Use Superserve sandboxes as the execution runtime for agents built with the OpenAI Agents SDK. - [MCP Server](https://docs.superserve.ai/integrations/mcp.md): Create, run, and manage Superserve sandboxes from any MCP client. ## OpenAPI Specs - [openapi](https://raw.githubusercontent.com/superserve-ai/sandbox/refs/heads/main/api/openapi.yaml)