# Docs for agents Source: https://compute.anonalabs.com/docs/agents/docs-for-agents Machine-readable docs: llms.txt and a Markdown copy of every page. These docs are built to be read by agents as well as people. | What | Where | | - | - | | Index of every page, with descriptions | [`/llms.txt`](https://compute.anonalabs.com/docs/llms.txt) | | Every page in one file | [`/llms-full.txt`](https://compute.anonalabs.com/docs/llms-full.txt) | | Any page as Markdown | Add `.md` to its URL, for example `/quickstart.md` | | One prompt that sets an agent up | [Self-onboarding prompt](/docs/agents/onboarding-prompt) | | The tool list an agent gets | [Agents via MCP](/docs/guides/mcp#tools) | | The route list | [`/api-reference/anona-openapi.yaml`](/docs/api-reference/anona-openapi.yaml) and [`/api-reference/e2b-openapi.yaml`](/docs/api-reference/e2b-openapi.yaml) | Start from `llms.txt`: it is small, and each line links to a Markdown page. Fetch `llms-full.txt` only when you need to search across everything. ## Tips for agents using the docs * Prefer the `.md` URL to the HTML page; it has no navigation or scripts. * Code blocks are runnable. Each one is run against a local stack before the docs ship, so copy them as written. * A **Coming soon** note means the feature is not available; do not call it. * Check [Limits](/docs/concepts/limits) before planning work that creates many sandboxes. # Self-onboarding prompt Source: https://compute.anonalabs.com/docs/agents/onboarding-prompt One prompt that connects a coding agent to Anona Compute and has it prove it works. Paste this into Claude Code, Codex or Cursor. The agent reads the prompt below, asks you to approve one sign-in and creates a sandbox to check the setup. ```text paste-into-your-agent Set up Anona Compute for me. Fetch https://compute.anonalabs.com/docs/agents/onboarding-prompt.md and follow it. ``` ## The prompt This is the page the agent reads. It is written for the agent. ```text onboarding-prompt You are connecting yourself to Anona Compute, which gives you disposable Linux microVM sandboxes. Work through these steps in order and stop to ask the human only where marked. 1. Check what you already have. - If you can already call tools named create_sandbox and run_command, skip to step 5. - Run `anona-compute whoami`. If it prints a user and organization, ask the human whether to use that account. Do not assume. 2. Install the CLI. - Run `anona-compute version`. If the command is missing, install it with `npm install -g @anona-labs/anona-compute` (needs Node.js) and run `anona-compute version` again. - If npm is not available and cannot be installed, ask the human for an API key (dashboard: https://compute.anonalabs.com, "API keys"), use the stock E2B SDK with E2B_DOMAIN=compute.anonalabs.com and E2B_API_KEY, and stop here. 3. Sign in. ASK THE HUMAN to approve. - Run `anona-compute login --no-browser`. Show the human the URL and code it prints and wait. They sign in, check the code, pick the organization and approve. - Run `anona-compute whoami` and confirm it succeeds. 4. Register the MCP server, then ask the human to restart you. - Claude Code: `claude mcp add anona-compute -- anona-compute mcp` - Codex: `codex mcp add anona-compute -- anona-compute mcp` - Other clients: command `anona-compute`, argument `mcp`. - Tools load when the client starts, so a restart is normal. 5. Prove it works. - Call create_sandbox with template "base" and timeout_seconds 300. - Call run_command with `uname -a && whoami`. - Call kill_sandbox. Report the output to the human. Rules while you work: - Delete every sandbox you create when you finish with it. Running sandboxes are billed. - Never print or store an API key in a file you commit. - Docs index: https://compute.anonalabs.com/docs/llms.txt ``` ## What the human sees One browser page asking them to approve a code. Nothing else needs their input unless the CLI is not installed or the agent needs a restart. > [card] [How it works](/docs/agents/overview) > > The sign-in flow, the ways to connect and the limits. # Agent self-onboarding Source: https://compute.anonalabs.com/docs/agents/overview A coding agent sets up Anona Compute from the terminal. You approve one browser sign-in. > For agents: fetch [`/llms.txt`](https://compute.anonalabs.com/docs/llms.txt) first (more in [Docs for agents](/docs/agents/docs-for-agents)). It indexes every page as Markdown. Give Claude Code, Codex, Cursor or any MCP client its own computers. The agent installs the CLI, asks you to approve a sign-in, registers the MCP server and creates a sandbox to prove it works. You do one thing: approve the sign-in in your browser. > [card] [Paste one prompt](/docs/agents/onboarding-prompt) > > Hand this to your agent and it does the rest. > [card] [Docs for agents](/docs/agents/docs-for-agents) > > `llms.txt` and a Markdown copy of every page. ## The flow ```mermaid sequenceDiagram participant Agent participant You participant AC as Anona Compute Agent->>AC: anona-compute login --no-browser AC-->>Agent: device code and verification URL Agent->>You: prints the URL and code You->>AC: open URL, check code, pick organization, approve AC-->>Agent: session held by the CLI for this machine Agent->>Agent: claude mcp add anona-compute -- anona-compute mcp Agent->>AC: tools/call create_sandbox, run_command, kill_sandbox ``` The sign-in is a standard device flow (RFC 8628). The agent never sees your password or an API key. The CLI trades its session for gateway tokens that last 15 minutes, and `anona-compute logout` revokes the session. ## Ways to connect | Path | Needs | Good for | Credential | | - | - | - | - | | **A. CLI and MCP** | The `anona-compute` binary | Claude Code, Codex, Cursor, any stdio MCP client | Browser sign-in held by the CLI | | **B. CLI with an API key** | The binary and an `ac_` key | Headless machines and CI | A scoped, expiring [API key](/docs/guides/ci) | | **C. Anona SDK** | `pip install anona-compute` or `npm install @anona-labs/compute-sdk` | An agent you wrote | An API key in `ANONA_API_KEY` | | **D. Stock E2B SDK** | `pip install e2b` and two environment variables | Code that already uses E2B | An API key as `E2B_API_KEY` | > [!NOTE] > > Install the CLI for paths A and B with `npm install -g @anona-labs/anona-compute`, or without Node.js from the [releases page](https://github.com/anonalabs/anona-compute-sdk/releases) or with `go install` (see [Install the CLI](/docs/cli/overview#install)). Path C is `pip install anona-compute` or `npm install @anona-labs/compute-sdk e2b`. Path D needs nothing from Anona; see [Migrate from E2B](/docs/migrate-from-e2b). ## Setup per path > [tab] A. CLI and MCP > > ```bash agent_login.sh > anona-compute login --no-browser # prints a URL and a code; the human approves > anona-compute whoami # user, organization, role > ``` > > Then register the server with the agent's client: > > ```bash claude_code.sh > claude mcp add anona-compute -- anona-compute mcp > ``` > > ```bash codex.sh > codex mcp add anona-compute -- anona-compute mcp > ``` > > Cursor and other clients: see [Agents via MCP](/docs/guides/mcp). MCP tools usually load when the client starts, so restart the agent once. > [tab] B. CLI with an API key > > Create a key in the [dashboard](https://compute.anonalabs.com) under **API keys**, with the least access the job needs. Then: > > ```bash agent_key.sh > printenv ANONA_API_KEY | anona-compute login --with-api-key > anona-compute whoami > ``` > [tab] C. Anona SDK > > ```text > pip install anona-compute # Python > npm install @anona-labs/compute-sdk e2b # TypeScript > export ANONA_API_KEY=ac_YOUR_API_KEY > ``` > > Both default to `compute.anonalabs.com` and read `ANONA_API_KEY`. `Sandbox` is the E2B SDK's, plus `live`, `ssh` and `size`; see [Python](/docs/sdk/python) and [TypeScript](/docs/sdk/typescript). > [tab] D. Stock E2B SDK > > ```bash agent_env.sh > pip install e2b > export E2B_DOMAIN=compute.anonalabs.com > export E2B_API_KEY=ac_YOUR_API_KEY > ``` > > The [quickstart](/docs/quickstart) has the first sandbox in Python and TypeScript, and [Migrate from E2B](/docs/migrate-from-e2b) lists what differs. ## What the agent gets Over MCP the agent can create, pause, resume, extend and delete sandboxes; run commands and background processes; read and write files; get a live-view link for you to watch, a preview link for a dev server it started, an SSH config and a desktop screenshot; and read its own usage. The full list is in [Agents via MCP](/docs/guides/mcp#tools). ## Limits * The agent can do what your role and credential allow, no more. Start it with `--read-only` after `mcp` to offer only the tools that do not change sandboxes. * A browser sign-in is a session for one machine. It cannot be used with the SDK or the REST API; those need an API key. * Sandbox limits (count and size) come from your plan. See [Limits](/docs/concepts/limits). * Billing is per active CPU and resident memory; an agent that leaves sandboxes running is billed. Tell it to delete them (the MCP tool is `kill_sandbox`) or let it [pause when idle](/docs/concepts/lifecycle#pause-when-idle). ## Troubleshooting **The agent says the tools are missing.** The client loads MCP tools at start. Restart it, then ask it to list its tools. **`login` waits forever.** The code expires. Run it again, open the URL it prints and check that the code matches. **`unauthorized` after a while.** The session was revoked, or the key expired. Run `anona-compute whoami`, then sign in again. **A create fails with a limit error.** Your plan's sandbox or memory limit is reached. The message names it; see [Troubleshooting](/docs/troubleshooting). # Create an API key Source: https://compute.anonalabs.com/docs/api-reference/api-keys/create-an-api-key /api-reference/anona-openapi.yaml post /v1/api-keys Creates an API key and returns its secret once. Dashboard sessions with the owner or admin role only. # List API keys Source: https://compute.anonalabs.com/docs/api-reference/api-keys/list-api-keys /api-reference/anona-openapi.yaml get /v1/api-keys Lists the organization's API keys (never their secrets). Dashboard sessions only: API keys cannot list or manage keys. Every role may list. # Revoke an API key Source: https://compute.anonalabs.com/docs/api-reference/api-keys/revoke-an-api-key /api-reference/anona-openapi.yaml delete /v1/api-keys/{keyID} Revokes a key at once. Dashboard sessions with the owner or admin role only. # Delete a secret Source: https://compute.anonalabs.com/docs/api-reference/credential-vault/delete-a-secret /api-reference/anona-openapi.yaml delete /v1/vault/secrets/{name} # List secrets Source: https://compute.anonalabs.com/docs/api-reference/credential-vault/list-secrets /api-reference/anona-openapi.yaml get /v1/vault/secrets Names, versions and bindings of the organization's secrets. Values are never returned. # Revoke a binding Source: https://compute.anonalabs.com/docs/api-reference/credential-vault/revoke-a-binding /api-reference/anona-openapi.yaml delete /v1/vault/bindings/{bindingID} Stops one secret from being injected for one host and header. # Rotate a secret Source: https://compute.anonalabs.com/docs/api-reference/credential-vault/rotate-a-secret /api-reference/anona-openapi.yaml post /v1/vault/secrets/{name}/versions Adds a new version. Egress proxies cache values for up to 60 seconds. With `allowedHosts`, the secret's allowed hosts are replaced in the same call; without it they stay as they are. Owners and admins, or unrestricted API keys (no scopes and no sandbox list). # Set a secret's allowed hosts Source: https://compute.anonalabs.com/docs/api-reference/credential-vault/set-a-secrets-allowed-hosts /api-reference/anona-openapi.yaml put /v1/vault/secrets/{name}/allowed-hosts Replaces the hosts a secret may be sent to. Narrowing takes effect at once: a binding whose host is no longer on the list stops working, and a rule naming that host is refused with 403. A secret stored before allowed hosts existed has an empty list and cannot be used until one is set here. Owners and admins, or unrestricted API keys (no scopes and no sandbox list). # Store a secret Source: https://compute.anonalabs.com/docs/api-reference/credential-vault/store-a-secret /api-reference/anona-openapi.yaml post /v1/vault/secrets Stores a secret, encrypted at rest. Reference it from a network rule as `${vault.}`; the egress proxy adds it to requests to that host, and the sandbox never sees the value. `allowedHosts` is required: a body without it, or with an empty list, is refused with 400. Owners and admins, or unrestricted API keys (no scopes and no sandbox list). # API reference Source: https://compute.anonalabs.com/docs/api-reference/introduction The REST API behind the SDKs and the CLI. Base URL: `https://api.compute.anonalabs.com` Most users never call it directly: the E2B SDK, the Anona extras and the CLI do. Two groups of routes: | Group | What | Source | | - | - | - | | [Sandboxes and templates](/docs/api-reference/sandboxes/create-sandbox-v2) | Create, list, get, delete (`kill` in the E2B SDK), pause, resume, connect, timeout, network update, template builds | The E2B OpenAPI spec (SDK 2.61.0), cut to the operations Anona serves | | [Anona Compute](/docs/api-reference/live-view/mint-a-viewer-token) | Viewer tokens, SSH certificates, network policy, credential vault, usage and billing, API keys | Written from the gateway's handlers | Both files are checked against a running gateway: every operation is called and each answer's status and body are validated against the spec. ## Authentication Send your API key in the `X-API-Key` header, or as `Authorization: Bearer ac_…`: ```bash api_auth.sh curl -sS https://api.compute.anonalabs.com/v2/sandboxes -H "X-API-Key: $ANONA_API_KEY" curl -sS https://api.compute.anonalabs.com/v2/sandboxes -H "Authorization: Bearer $ANONA_API_KEY" ``` The `/v1/api-keys` routes accept only dashboard sessions; manage keys in the dashboard. Changing the team network settings and the credential vault needs an owner or admin session, or an [unrestricted API key](/docs/guides/ci#create-a-key-for-ci) (no scopes and no sandbox list). Other API keys can read them, unless they have a sandbox list. ## Errors Errors have the E2B shape, so the SDKs raise their usual exceptions: ```json { "code": 429, "message": "concurrent sandbox limit reached (100): the Pro plan runs at most 100 sandboxes at once - pause or delete one, or upgrade the plan", "error_code": "plan_limit_exceeded", "limit_name": "concurrent_sandboxes", "limit": 100, "current": 100, "plan": "pro", "requestId": "3f2c9a0e7b1d4c55a8e6f0b2d4c6e8a1" } ``` `requestId` is also sent as the `X-Request-Id` header. Quote it when you report a problem. A refusal at a plan limit also says which limit (`limit_name`), the limit, what is in use now (`current`) and your plan; see [limits](/docs/concepts/limits). | Status | Meaning | | - | - | | 400 | Invalid request, or a feature not supported (the message says which) | | 401 | Missing, unknown, revoked or expired API key | | 402 | The credit is spent (`error_code` `credit_exhausted`) | | 403 | The key's scopes or your role do not allow this; or the organization is suspended; or a plan limit only you can clear (`error_code` `plan_limit_exceeded`): API keys, templates, template storage, paused sandboxes, a size above your plan's largest, or on Free the month's included vCPU-hours or egress (`limit_name` `included_vcpu_hours` or `included_egress_gb`) | | 404 | Not found, or not yours (the same answer). On create, `error_code` `template_not_found` | | 409 | The sandbox is in the wrong state (for example, a request to a paused sandbox's URL). On create, `error_code` `template_not_ready`: the template exists but cannot start a sandbox; retrying does not help until it is rebuilt | | 413 | The request body, or a template's build context, is too large | | 429 | A plan limit on what runs at once (`error_code` `plan_limit_exceeded`: sandboxes, vCPU, or sandboxes at the largest size), or a rate limit (`error_code` `rate_limited`, with `Retry-After`): your plan's requests or sandbox creates per minute, the team-wide rates, or failed sign-ins from one address | | 500 | An internal error. On create, `error_code` `sandbox_create_failed` | | 501 | Not available on this platform (for example, changing a running sandbox's network policy) | | 502 | Something behind the API could not be reached: the sandbox itself, or the template or usage service | | 503 | Not available yet; retry after `Retry-After` seconds. `error_code` says why: `sandbox_engine_starting` (the platform is still starting up), `sandbox_engine_unavailable` (it could not be reached), or `sandbox_capacity_unavailable` (no capacity right now; on a resume, the sandbox stays paused and the same request resumes it once a host has room) | | 504 | The platform did not answer in time and the outcome is unknown (`Should-Retry: false`). On create, `error_code` `sandbox_create_failed`: list your sandboxes before retrying, or you may start two | | 507 | Snapshot storage is full (`error_code` `sandbox_snapshot_storage_full`): pause is refused, and retrying does not help | ## Service status [status.anonalabs.com](https://status.anonalabs.com) shows whether the API, sandboxes, sandbox URLs, the dashboard and these docs are up. `GET https://api.compute.anonalabs.com/statusz` answers the same question for a script. It needs no API key, answers `200` whenever the API can answer at all, and puts the verdict in the body. The result is cached for 15 seconds. ```json { "status": "operational", "version": "b39ca12175eb", "checked_at": "2026-11-14T13:48:12Z", "components": { "api": { "status": "operational" }, "database": { "status": "operational" }, "sandbox_engine": { "status": "operational", "state": "asleep", "note": "asleep, starts on next create" }, "capacity": { "status": "operational" } } } ``` Each `status` is `operational`, `degraded` or `down`, and the top-level `status` is the worst of the components. `sandbox_engine.state` is `awake`, `asleep`, `waking`, `going_to_sleep` or `unknown`. An engine that is asleep is working as designed: the next create starts it, and that create takes longer. A request that gets no answer at all, or a `5xx`, means the API itself is down. ## Sandbox traffic Commands, files and terminals do not go to the API host. They go to the sandbox's own `envd` at `https://49983-.sbx.compute.anonalabs.com` (Connect RPC, E2B's `envd` protocol), with the sandbox's access token from the create response. Live view and SSH use `wss://stream.compute.anonalabs.com`. # Latest thumbnail Source: https://compute.anonalabs.com/docs/api-reference/live-view/latest-thumbnail /api-reference/anona-openapi.yaml get /v1/sandboxes/{sandboxID}/thumbnail The sandbox's latest 320 px WebP thumbnail (its screen, or its active Chrome page). The sandbox grabs frames only while someone asks. Same access as a view token. # Mint a viewer token Source: https://compute.anonalabs.com/docs/api-reference/live-view/mint-a-viewer-token /api-reference/anona-openapi.yaml post /v1/sandboxes/{sandboxID}/viewer-tokens Mints a short-lived, signed viewer token for one sandbox and returns the embed URL that opens the live view with it. The token travels in the URL fragment (`#t=...`), which browsers never send to a server. `control` scope needs an API key, or a dashboard role of member or above. The key needs the `sandboxes:use` scope and, if it is limited to a list of sandboxes, this sandbox must be on it. # Revoke every viewer Source: https://compute.anonalabs.com/docs/api-reference/live-view/revoke-every-viewer /api-reference/anona-openapi.yaml post /v1/sandboxes/{sandboxID}/viewer-tokens:revoke-all Closes every open live view of the sandbox and invalidates every viewer token issued for it so far, by moving the sandbox's revocation epoch forward. Needs the same access as a `control` token. # Viewer token keys Source: https://compute.anonalabs.com/docs/api-reference/live-view/viewer-token-keys /api-reference/anona-openapi.yaml get /.well-known/stream-jwks.json The Ed25519 public keys (JWKS) that verify viewer tokens. # Effective policy of a sandbox Source: https://compute.anonalabs.com/docs/api-reference/network/effective-policy-of-a-sandbox /api-reference/anona-openapi.yaml get /v1/sandboxes/{sandboxID}/network/effective The policy the sandbox runs with, and which layer it came from. # Get team egress settings Source: https://compute.anonalabs.com/docs/api-reference/network/get-team-egress-settings /api-reference/anona-openapi.yaml get /v1/network The organization's default egress policy for new sandboxes (used when neither the create request nor the template has one), what it compiles to under your plan, and the plan's limits. Any role or key may read it. # Set a template's egress policy Source: https://compute.anonalabs.com/docs/api-reference/network/set-a-templates-egress-policy /api-reference/anona-openapi.yaml put /v1/templates/{templateID}/network The default policy of sandboxes created from one of your own templates. The built-in templates are read-only (403); custom templates are coming soon. # Set team egress settings Source: https://compute.anonalabs.com/docs/api-reference/network/set-team-egress-settings /api-reference/anona-openapi.yaml put /v1/network Replaces the team egress settings. The body is a network policy in the E2B shape (the fields of a create's `network` object, plus `allow_internet_access`). Owners and admins, or unrestricted API keys (no scopes and no sandbox list). Header values in `rules` may only be vault placeholders such as `Bearer ${vault.openai_key}`. A rule here makes one binding that every sandbox created under these settings uses. # Access settings Source: https://compute.anonalabs.com/docs/api-reference/sandbox-access/access-settings /api-reference/anona-openapi.yaml get /v1/sandboxes/{sandboxID}/access Public traffic, public ports and the idle-pause time of a sandbox. Needs `sandboxes:read`. # Create a preview link Source: https://compute.anonalabs.com/docs/api-reference/sandbox-access/create-a-preview-link /api-reference/anona-openapi.yaml post /v1/sandboxes/{sandboxID}/preview-links A signed link that opens one port of the sandbox in a browser until it expires. The edge exchanges it for a cookie scoped to that port's host. Port 49983 (envd) cannot be shared. Needs `sandboxes:use`. # Make a port public or private Source: https://compute.anonalabs.com/docs/api-reference/sandbox-access/make-a-port-public-or-private /api-reference/anona-openapi.yaml put /v1/sandboxes/{sandboxID}/ports/{port} # Rename a sandbox Source: https://compute.anonalabs.com/docs/api-reference/sandbox-access/rename-a-sandbox /api-reference/anona-openapi.yaml put /v1/sandboxes/{sandboxID}/name Sets the sandbox's human name, which is the `name` key of its metadata. Set it at create time with `metadata: {"name": "..."}` and filter on it with the ordinary metadata filter. Other metadata keys are left alone; the sandbox ID stays the identifier. `""` removes the name. # Revoke every preview link Source: https://compute.anonalabs.com/docs/api-reference/sandbox-access/revoke-every-preview-link /api-reference/anona-openapi.yaml post /v1/sandboxes/{sandboxID}/preview-links:revoke-all Ends every preview link and every live-view token of the sandbox. # Set pause when idle Source: https://compute.anonalabs.com/docs/api-reference/sandbox-access/set-pause-when-idle /api-reference/anona-openapi.yaml put /v1/sandboxes/{sandboxID}/auto-pause Pause the sandbox after this many minutes with no traffic, sessions or envd processes. 0 turns it off. # Connect sandbox (v2) Source: https://compute.anonalabs.com/docs/api-reference/sandboxes/connect-sandbox-v2 /api-reference/e2b-openapi.yaml post /v2/sandboxes/{sandboxID}/connect Returns sandbox details. If the sandbox is paused, it will be resumed. TTL is only extended. The request body is optional; an omitted timeout defaults to 300 seconds. Anona: resuming a paused sandbox when no sandbox host has room for it is `503` `sandbox_capacity_unavailable` with `Should-Retry: true` and `Retry-After`. The sandbox stays paused and nothing in it is lost; a host is started for it, and the same request resumes it once there is room. # Create sandbox (v2) Source: https://compute.anonalabs.com/docs/api-reference/sandboxes/create-sandbox-v2 /api-reference/e2b-openapi.yaml post /v2/sandboxes Create a sandbox from the template. All system communication with the sandbox is secured. Anona: `size` (`small`, `medium`, `large` or `xl`) sets the sandbox's vCPU, memory and disk; an E2B SDK can send it as metadata `anona.size` instead. Without it the sandbox runs at its template's own size, or on Free at the smallest size the template allows (Small for `base`). A size below the template's minimum is `400` `sandbox_size_not_available`, and one above your plan's largest size is `403` `plan_limit_exceeded`; the first sandbox at a size the template was not built at may get `503` `sandbox_size_preparing` with `Retry-After` while that size is prepared (see Sandbox sizes). Over a plan limit on what runs at once (sandboxes, vCPU, or sandboxes at the largest size) is `429` `plan_limit_exceeded` with `limit_name`, `limit`, `current` and `plan`. `timeout` also accepts `-1` for no deadline. `lifecycle.onTimeout: pause` (sent by the SDK as `autoPause`) pauses instead of deleting. A sandbox without a deadline reports `endAt` `9999-12-31T23:59:59Z`. `network.egressProxy`, `volumeMounts`, `iam` and `autoPauseMemory: false` are refused with 400, and the `Idempotency-Key` header is not supported. # Fork sandbox Source: https://compute.anonalabs.com/docs/api-reference/sandboxes/fork-sandbox /api-reference/e2b-openapi.yaml post /sandboxes/{sandboxID}/fork Fork the sandbox: checkpoint the running sandbox in place (it is briefly paused, snapshotted with its full memory state, and resumed on its node, keeping its ID and expiration untouched) and create count new sandboxes from that snapshot. Returns one result per requested fork, each carrying either the created sandbox or the error that prevented it from starting. A non-201 status means the request failed before any fork was attempted. Anona: the sandbox is frozen only while its memory delta is written (about 0.1 s, longer right after it has touched a lot of memory) and then keeps running with its own ID and expiration. Each fork is a new sandbox: it takes a slot of your concurrent-sandbox limit and is billed like any other sandbox, and the forks inherit the source sandbox's template, metadata, timeout policy and network policy, with the `timeout` of this request. `count` above the room left in your plan is not an error for the whole request: the forks that fit are created and each of the others carries `429` `plan_limit_exceeded` (with `limit_name`, `limit`, `current` and `plan`) in its own result entry, while a platform at capacity reports `503` per fork. A source sandbox that is not running is `409`, and nothing is forked. # Kill sandbox Source: https://compute.anonalabs.com/docs/api-reference/sandboxes/kill-sandbox /api-reference/e2b-openapi.yaml delete /sandboxes/{sandboxID} Kill a sandbox # List sandboxes (v2) Source: https://compute.anonalabs.com/docs/api-reference/sandboxes/list-sandboxes-v2 /api-reference/e2b-openapi.yaml get /v2/sandboxes List all sandboxes # Pause sandbox Source: https://compute.anonalabs.com/docs/api-reference/sandboxes/pause-sandbox /api-reference/e2b-openapi.yaml post /sandboxes/{sandboxID}/pause Pause the sandbox # Refresh sandbox Source: https://compute.anonalabs.com/docs/api-reference/sandboxes/refresh-sandbox /api-reference/e2b-openapi.yaml post /sandboxes/{sandboxID}/refreshes Refresh the sandbox extending its time to live # Sandbox Source: https://compute.anonalabs.com/docs/api-reference/sandboxes/sandbox /api-reference/e2b-openapi.yaml get /sandboxes/{sandboxID} Get a sandbox by id # Set sandbox timeout Source: https://compute.anonalabs.com/docs/api-reference/sandboxes/set-sandbox-timeout /api-reference/e2b-openapi.yaml post /sandboxes/{sandboxID}/timeout Set the timeout for the sandbox. The sandbox will expire x seconds from the time of the request. Calling this method multiple times overwrites the TTL, each time using the current timestamp as the starting point to measure the timeout duration. Anona: `-1` removes the deadline. # Update sandbox network Source: https://compute.anonalabs.com/docs/api-reference/sandboxes/update-sandbox-network /api-reference/e2b-openapi.yaml put /sandboxes/{sandboxID}/network Update the network configuration for a running sandbox. Replaces the current egress rules with the provided configuration. Omitting field clears it. Anona: the update replaces the sandbox's policy and goes through the same platform floor and plan limits as a create. An update without `allow_internet_access` keeps the sandbox's current internet setting. `egressProxy` is refused with 400, as on create. A rule in `rules` that needs a new credential binding needs the same permission as on create (see Networking). # Gateway version Source: https://compute.anonalabs.com/docs/api-reference/service/gateway-version /api-reference/anona-openapi.yaml get /version # Health check Source: https://compute.anonalabs.com/docs/api-reference/service/health-check /api-reference/anona-openapi.yaml get /healthz # Sign an SSH certificate Source: https://compute.anonalabs.com/docs/api-reference/ssh/sign-an-ssh-certificate /api-reference/anona-openapi.yaml post /v1/sandboxes/{sandboxID}/ssh-certs Signs an OpenSSH user certificate for the given public key. It is valid for 10 minutes, for this sandbox only, and logs in as `user`. It permits a PTY and port forwarding, so `ssh -L/-R`, `scp`, `rsync` and editor remote extensions work. Connect through the stream relay with `ProxyCommand anona-compute ssh --proxy `. Needs an API key or a dashboard role of member or above, with the `sandboxes:use` scope. # SSH user CA public key Source: https://compute.anonalabs.com/docs/api-reference/ssh/ssh-user-ca-public-key /api-reference/anona-openapi.yaml get /.well-known/anona-ssh-user-ca.pub The public key of the CA that signs sandbox SSH certificates, in authorized_keys form. # Build from a Dockerfile Source: https://compute.anonalabs.com/docs/api-reference/templates/build-from-a-dockerfile /api-reference/anona-openapi.yaml post /v1/templates/{templateID}/builds/{buildID}/dockerfile Starts a build from a Dockerfile and a build context uploaded through the E2B file links, instead of E2B's step list. This is what `anona-compute template build` uses. # Check template alias Source: https://compute.anonalabs.com/docs/api-reference/templates/check-template-alias /api-reference/e2b-openapi.yaml get /templates/aliases/{alias} Check if template with given alias exists # Create template (v3) Source: https://compute.anonalabs.com/docs/api-reference/templates/create-template-v3 /api-reference/e2b-openapi.yaml post /v3/templates Create a new template Anona builds the image with BuildKit in an isolated builder, adds the Anona runtime layer (envd), pushes it and registers it. Every `FROM` is pinned by digest, `EXPOSE 49983` (envd) is refused, and private registry credentials (`fromImageRegistry`) are not supported yet. # Delete template Source: https://compute.anonalabs.com/docs/api-reference/templates/delete-template /api-reference/e2b-openapi.yaml delete /templates/{templateID} Delete a template Anona: sandboxes already running from the template keep running; new creates no longer resolve its name. # List template builds Source: https://compute.anonalabs.com/docs/api-reference/templates/list-template-builds /api-reference/e2b-openapi.yaml get /templates/{templateID} List all builds for a template # List templates (v2) Source: https://compute.anonalabs.com/docs/api-reference/templates/list-templates-v2 /api-reference/e2b-openapi.yaml get /v2/templates List all templates # Start template build (v2) Source: https://compute.anonalabs.com/docs/api-reference/templates/start-template-build-v2 /api-reference/e2b-openapi.yaml post /v2/templates/{templateID}/builds/{buildID} Start the build # Stream build events Source: https://compute.anonalabs.com/docs/api-reference/templates/stream-build-events /api-reference/anona-openapi.yaml get /v1/templates/{templateID}/builds/{buildID}/events Newline-delimited JSON: one object per log line and status change, ending when the build is ready or failed. `anona-compute template build` and the dashboard follow a build with it. # Template build file upload URL Source: https://compute.anonalabs.com/docs/api-reference/templates/template-build-file-upload-url /api-reference/e2b-openapi.yaml get /templates/{templateID}/files/{hash} Get an upload link for a tar file containing build layer files # Template build logs Source: https://compute.anonalabs.com/docs/api-reference/templates/template-build-logs /api-reference/e2b-openapi.yaml get /templates/{templateID}/builds/{buildID}/logs Get template build logs # Template build status Source: https://compute.anonalabs.com/docs/api-reference/templates/template-build-status /api-reference/e2b-openapi.yaml get /templates/{templateID}/builds/{buildID}/status Get template build info # Plan, rates and invoices Source: https://compute.anonalabs.com/docs/api-reference/usage-and-billing/plan-rates-and-invoices /api-reference/anona-openapi.yaml get /v1/billing Dashboard owners and admins; API keys with the `billing:read` scope. # Usage and cost Source: https://compute.anonalabs.com/docs/api-reference/usage-and-billing/usage-and-cost /api-reference/anona-openapi.yaml get /v1/usage Metered usage and its cost for a billing period: meters, totals (rated, not yet rated, credit, due) with a projection for the current month, a daily breakdown, every template, and the period's sandboxes, most expensive first, a page at a time. Dashboard sessions of any role; API keys with the `usage:read` scope. `sandboxes` holds `limit` rows (50 unless you pass it, at most 1000). `sandboxCount` is how many sandboxes had usage in the period, on every page. While more remain the response carries `nextCursor`: pass it back as `cursor`, with the same `period`, for the next page. A closed period pages the same way every time; in the current month costs are still moving, so a sandbox can change pages between requests. To read one sandbox's row wherever it ranks, pass `sandboxId` instead. Usage arrives a minute at a time: a minute is included within about 35 seconds of its end, so the minute a sandbox was deleted in shows up that long after the minute is over, not at the delete. Read again after that before comparing running time with a sandbox's lifetime. # Create a webhook endpoint Source: https://compute.anonalabs.com/docs/api-reference/webhooks-and-telemetry/create-a-webhook-endpoint /api-reference/anona-openapi.yaml post /v1/webhooks Returns the signing secret (`whsec_...`) once. URLs must be https with a public host. # Delete a webhook endpoint Source: https://compute.anonalabs.com/docs/api-reference/webhooks-and-telemetry/delete-a-webhook-endpoint /api-reference/anona-openapi.yaml delete /v1/webhooks/{webhookID} # Delivery log Source: https://compute.anonalabs.com/docs/api-reference/webhooks-and-telemetry/delivery-log /api-reference/anona-openapi.yaml get /v1/webhooks/{webhookID}/deliveries Newest first, with every attempt. # Get a webhook endpoint Source: https://compute.anonalabs.com/docs/api-reference/webhooks-and-telemetry/get-a-webhook-endpoint /api-reference/anona-openapi.yaml get /v1/webhooks/{webhookID} # Get the OpenTelemetry export Source: https://compute.anonalabs.com/docs/api-reference/webhooks-and-telemetry/get-the-opentelemetry-export /api-reference/anona-openapi.yaml get /v1/otel-export # List webhook endpoints Source: https://compute.anonalabs.com/docs/api-reference/webhooks-and-telemetry/list-webhook-endpoints /api-reference/anona-openapi.yaml get /v1/webhooks The organization's endpoints and the event catalog. Owners and admins, or keys with `integrations:manage`. # Remove the OpenTelemetry export Source: https://compute.anonalabs.com/docs/api-reference/webhooks-and-telemetry/remove-the-opentelemetry-export /api-reference/anona-openapi.yaml delete /v1/otel-export # Resend a delivery Source: https://compute.anonalabs.com/docs/api-reference/webhooks-and-telemetry/resend-a-delivery /api-reference/anona-openapi.yaml post /v1/webhooks/{webhookID}/deliveries/{deliveryID}/resend Queues the delivery again, also a dead one; the retry budget starts over. # Rotate the signing secret Source: https://compute.anonalabs.com/docs/api-reference/webhooks-and-telemetry/rotate-the-signing-secret /api-reference/anona-openapi.yaml post /v1/webhooks/{webhookID}/rotate-secret Returns the new secret once; the previous one keeps signing for 24 hours. # Send a test event Source: https://compute.anonalabs.com/docs/api-reference/webhooks-and-telemetry/send-a-test-event /api-reference/anona-openapi.yaml post /v1/webhooks/{webhookID}/test Queues a `webhook.test` event to this endpoint. # Set the OpenTelemetry export Source: https://compute.anonalabs.com/docs/api-reference/webhooks-and-telemetry/set-the-opentelemetry-export /api-reference/anona-openapi.yaml put /v1/otel-export The OTLP/HTTP base URL (protobuf to `/v1/metrics` and `/v1/traces`), headers (encrypted at rest, never returned; omit to keep the stored ones) and whether it is enabled. # Update a webhook endpoint Source: https://compute.anonalabs.com/docs/api-reference/webhooks-and-telemetry/update-a-webhook-endpoint /api-reference/anona-openapi.yaml patch /v1/webhooks/{webhookID} Any of `name`, `url`, `events`, `enabled`. # Changelog Source: https://compute.anonalabs.com/docs/changelog What changed, newest first. **2026-11-17** Billing ## Billed per second, with a 1-minute minimum * A sandbox that runs less than a minute is now billed one minute of the vCPU and memory it is given. After the first minute nothing changes: every second is billed, so a sandbox that runs 90 seconds is billed 90 seconds. * A sandbox deleted within its first few seconds used to get no usage record at all, so it was never billed and `anona-compute usage --sandbox ` said it had no usage. Every sandbox that ran now gets one. * The minimum is worked out a few minutes after a sandbox ends, and applies to sandboxes that end from today. A sandbox ended by a platform fault is not billed a minimum. **2026-11-16** CLI 0.4.1 ## CLI 0.4.1 `npm install -g @anona-labs/anona-compute` installs 0.4.1. * `anona-compute login` with no `--web-url` opened a sign-in page that answered `404`: the default dashboard URL was `https://app.`, which does not exist. It is now `https://`, where the dashboard and the device sign-in live. On 0.4.0, pass `--web-url https://compute.anonalabs.com`. * The `vault --help` example now passes `--allow-out` with `--no-internet`: a vault rule injects into requests to its host but does not open that host, so without `--allow-out` the request is refused. **2026-11-14** SDK 0.3.0 ## SDK 0.3.0: creates wait for capacity In `anona-compute` 0.3.0 (Python) and `@anona-labs/compute-sdk` 0.3.0 (TypeScript). * `Sandbox.create` and `Sandbox.connect` wait when the fleet is full instead of failing at once: a `503` marked `Should-Retry: true` (`sandbox_capacity_unavailable` while a host starts, and the platform starting) is retried after its `Retry-After`, held between 1 and 30 seconds, for up to 10 minutes. Set `wait_for_capacity` / `waitForCapacityMs` per call or in `configure()`, or `ANONA_COMPUTE_CAPACITY_WAIT`; `0` turns it off. `on_capacity_wait` / `onCapacityWait` is called before each wait. Plan limits and every other error are not retried. See [Python](/docs/sdk/python#waiting-for-capacity) and [TypeScript](/docs/sdk/typescript#waiting-for-capacity). **2026-11-14** CLI 0.4.0 ## CLI 0.4.0 `npm install -g @anona-labs/anona-compute` installs 0.4.0. * `resume` waits for capacity like `create`, with `--capacity-wait` (default 10 minutes) and progress lines on stderr. Both also wait out `sandbox_size_preparing`, and hold each wait's `Retry-After` between 1 and 30 seconds with a little jitter. * A plan limit (`error_code` `plan_limit_exceeded`) exits 5, like a rate limit, whether the gateway answered `429` or `403`; `--size` help says Free defaults to the smallest size. * `anona-compute usage` shows the month against what your plan includes: vCPU-hours, memory, egress and storage, what is over, and whether Free has stopped. **2026-11-14** No maximum lifetime ## No plan has a maximum sandbox lifetime Free and Starter no longer cap a sandbox at one hour and 24 hours. Every plan accepts `timeout=-1`, which means no deadline, and any longer timeout. Free is still bounded by its month's included vCPU-hours: running sandboxes pause when those are used up. Let a sandbox without a deadline [pause when idle](/docs/concepts/lifecycle#pause-when-idle) so it stops using them. See [Lifecycle](/docs/concepts/lifecycle#no-time-limit). **2026-11-13** New plans and pricing ## Plans include usage every month Free, Starter, Pro and Scale now cost $0, $19, $99 and $399 a month and include 100, 330, 1,800 and 7,500 vCPU-hours (each with 2 GiB of memory per vCPU) and 5, 25, 100 and 250 GB of egress every calendar month. Usage is billed on the vCPU and memory a sandbox is given, per second: $0.04 a vCPU-hour and $0.01 a GiB-hour, so 1 vCPU and 2 GiB is $0.06 an hour. Paused sandboxes and snapshots are $0.0000685 per GiB-hour, egress \$0.12 per GB. See [Pricing](/docs/pricing). * Free stops when its month's included usage is used up: new sandboxes and resumes get `403` `plan_limit_exceeded` and running sandboxes are paused until the month ends. Paid plans keep running and are billed for what is over on the next invoice. * Free's public internet egress stays off for now; its 5 GB a month applies once a real-time cap is in place. * Owners and admins get an email at 80% and 100% of the month's included vCPU-hours and egress. * Credit you already have keeps paying for usage over the included amount until it is spent. New credit codes, sign-up credit, invites and referral rewards are no longer given; discount codes still work. * `GET /v1/usage` and the dashboard show the month against what the plan includes; `anona-compute usage` does too from the next CLI release. **2026-11-13** Plan limits ## Every plan limit is enforced, and says which Each plan's limits are now enforced as published on [Regions and limits](/docs/concepts/limits): sandboxes and vCPU at once, the largest size (Free and Starter Medium, Pro Large, Scale XL; Free at most two Medium at once), sandbox creates and API requests per minute, API keys, custom templates (Free: 2), template storage and paused sandboxes. A refusal has `error_code` `plan_limit_exceeded` with `limit_name`, `limit`, `current` and `plan`: `429` for what runs at once, `403` for the rest. Rate limits stay `429` `rate_limited` with `Retry-After`. Nothing you already have is stopped if your plan's limits are lower; new things are refused until you are under them. * On Free, a sandbox created without a size runs at the smallest size its template allows: Small for `base`, `python`, `node` and `code-interpreter`, Medium for the desktops. * Template storage counts each template's current build only. * At the paused-sandbox limit, a pause you ask for is refused, and an idle pause or a pause on timeout deletes the sandbox instead (end reason `paused_limit`). * Free deletes a paused sandbox 14 days after it was paused, after emailing the team's owners and admins three days before. * With the next CLI release, `anona-compute` exits 5 on a plan limit. **2026-11-13** CLI 0.3.1 ## CLI 0.3.1 * `anona-compute usage --top N` reads as many pages of `GET /v1/usage` as it needs, and `--sandbox ` shows one sandbox's row wherever it ranks. * When a template's newest build fails while an earlier build still serves it, `template list` shows `ready (last build failed)`, and `template info` adds a `Last build` line with the build ID and the error. With `--json`, `last_build_id`, `last_build_status` and `last_build_error`. **2026-11-13** Usage API: every sandbox, documented rows ## Every sandbox in GET /v1/usage `GET /v1/usage` used to list only the 50 most expensive sandboxes of a period. It now pages: `limit` (up to 1000) and `cursor`, with `nextCursor` in the response, or `sandboxId` for one sandbox's row. The API reference describes every field of the sandbox and template rows, and which are allocated (size times running time) and which are consumed. In the CLI, `anona-compute usage --top N` reads as many pages as it needs and `--sandbox ` shows one row; both come with the next CLI release (not 0.3.0). ## Running time matches the sandbox's lifetime Running time is now clipped to a sandbox's start and delete times and no longer misses the seconds before its first sample, so it lands within a few seconds of start to delete instead of anywhere from about 15 seconds short to a minute over. See [What counts](/docs/usage-and-billing#what-counts). **2026-11-13** CLI 0.3.0 ## CLI 0.3.0 `npm install -g @anona-labs/anona-compute` installs 0.3.0. It is also the first CLI release with binaries on the public [releases page](https://github.com/anonalabs/anona-compute-sdk/releases) (`cli-v0.3.0`, with `SHA256SUMS`) and through `go install github.com/anonalabs/anona-compute-sdk/cli/cmd/anona-compute@latest`. * **Breaking for scripts:** with `--json`, `list`, `ps`, `template list` (with or without `--all`) and `config list` print one JSON array, `[]` when there is nothing to list, instead of one object per line. An empty list used to print nothing, which is not JSON. Read items with `jq '.[]'`, or a field with `jq -r '.[].sandbox_id'`. Other commands still print one object per line. * `template info` shows a built-in template's vCPU, memory and disk from the template catalog, as `template list --all` does. It used to show a new build's defaults (2 vCPU and 2048 MiB for both `base` and `desktop`). Its "Minimum size" line now says that a built-in's minimum is set per template. **2026-11-13** Open-source CLI and SDKs ## The CLI and SDKs are open source The `anona-compute` CLI, the Python `anona-compute` and TypeScript `@anona-labs/compute-sdk` SDK extras, the agent skill and the examples are public under Apache-2.0 in [anona-compute-sdk](https://github.com/anonalabs/anona-compute-sdk). npm stays the main way to install the CLI, and there are now two more: * Download the binary for your platform from the [releases page](https://github.com/anonalabs/anona-compute-sdk/releases), with `SHA256SUMS`. * `go install github.com/anonalabs/anona-compute-sdk/cli/cmd/anona-compute@latest`. The SDK extras are on PyPI (`pip install anona-compute`) and npm (`npm install @anona-labs/compute-sdk e2b`). See [Install the CLI](/docs/cli/overview#install). **2026-11-12** CLI 0.2.0 ## CLI 0.2.0 on npm `npm install -g @anona-labs/anona-compute` now installs 0.2.0: * `create` and `run` take `--size small|medium|large|xl`; `info` and `template info` show sizes. * `create --count` runs creates independently, up to `--parallel` at once (default 4), each with its own `--create-timeout`, and prints a created and failed summary. One failing create no longer holds up the batch. * A create held while a host starts is waited out for up to `--capacity-wait` (default 10 minutes, or `ANONA_COMPUTE_CAPACITY_WAIT`) with progress lines, instead of failing after 60 seconds. **2026-11-12** Sandbox sizes ## Sandbox sizes: Small, Medium, Large and XL Create a sandbox at a size that sets its vCPU, memory and disk: Small (1 vCPU, 2 GiB, 10 GB), Medium (2, 4 GiB, 20 GB), Large (4, 8 GiB, 40 GB) or XL (8, 16 GiB, 80 GB). `anona-compute create --size large`, `size` in the create body, `Sandbox.create(..., size="large")` in Python, `withSize("large")` in TypeScript, or the size picker in the console. A template's own vCPU, memory and disk are now its minimum requirements, so one template runs at every size at or above them. Without a size, nothing changes: a sandbox runs at its template's own size. See [Sandbox sizes](/docs/concepts/sizes). **2026-11-09** Docs move to /docs; dashboard password reset ## Docs live at compute.anonalabs.com/docs The docs are now at [compute.anonalabs.com/docs](https://compute.anonalabs.com/docs). The agent setup prompt, the welcome email and the `llms.txt` links all point there: ```text Set up Anona Compute for me. Fetch https://compute.anonalabs.com/docs/agents/onboarding-prompt.md and follow it. ``` ## Dashboard * **Forgot password.** Email and password accounts can reset a lost password from the sign-in page. The link works once and expires after an hour; resetting signs out your other sessions. * **Feedback on actions.** Pause, resume, extend, delete and key changes confirm with a short toast. * **Phones.** Sign out is reachable on narrow screens, and there is a skip link for keyboard users. * **Billing and usage.** The usage chart stays readable when one day dwarfs the rest, with a **Show as a table** view of exact values. **2026-11-05** Idle pause everywhere; timeouts are enforced ## Pause a sandbox when nothing is using it A sandbox can already pause itself once nothing has used it for a while, but until now only the dashboard and raw API could ask for it, and the dashboard offered one fixed time. It is now in every surface, with the time your choice. * **SDKs**: `sandbox.idle_pause.set(15)` in Python, `sandbox.idlePause.set(15)` in TypeScript, plus `get()` and `off()`. Neither SDK could reach the feature before. * **CLI**: `--idle-pause 15m` on `create` and `run`, and `anona-compute idle-pause SANDBOX_ID 1h` (or `off`) on a sandbox that is already running. * **MCP**: `create_sandbox` takes `idle_pause_minutes`. * **Dashboard**: picking the lifetime **No limit (pauses when idle)** now shows an idle time beside it - team default, 5 minutes, 15, 30, 1 hour, 2, 6 or 24 - and the same times are in **Extend** on a running sandbox. Idle means no request to any port, no open terminal, live view, SSH session or byte pipe, and no process `envd` started still running. **Work the sandbox started by itself does not count**, so a background loop nobody is watching will still pause. A paused sandbox costs no compute, only snapshot storage. ```bash idle_pause_changelog.sh SANDBOX_ID=$(anona-compute create -t base --timeout never --idle-pause 15m --json | jq -r .sandbox_id) anona-compute idle-pause "$SANDBOX_ID" 1h ``` ## Sandbox timeouts are now enforced The gateway's timeout controller ran in report-only mode: it logged what it would do and did nothing. A sandbox whose timeout had passed could stay listed as running indefinitely. It now acts, so a sandbox ends at its deadline - deleted, or paused if it was created with pause-on-timeout. See [Lifecycle](/docs/concepts/lifecycle). **2026-11-05** CLI: credential vault and egress rules ## Manage the credential vault from the CLI * **`anona-compute vault`**: `list`, `create`, `rotate`, `allowed-hosts`, `delete` and `unbind`. Until now the vault was reachable only from the dashboard or by calling the API yourself. * There is no `vault get`. No response from the API carries a secret's value - the sandbox that uses it does not see it either - so there is nothing for such a command to print. * Values are read from `--value-file` or from stdin, never from an argument: an argument is kept in your shell's history file and is visible in the process table. A single trailing newline is stripped, so a token saved from an editor does not carry one into the header. * **Egress rules on `create` and `run`**: `--allow-out `, `--vault-inject HOST:HEADER=[bearer:|basic:]SECRET`, and `--network-file ` for the whole policy document. ```bash vault_quickstart.sh anona-compute vault create github_token --host api.github.com --value-file token.txt anona-compute create --no-internet \ --allow-out api.github.com \ --vault-inject api.github.com:Authorization=bearer:github_token ``` See [Credentials without exposing them](/docs/concepts/networking#credentials-without-exposing-them). **2026-11-04** CLI: stdin, exit codes, JSON keys, doctor ## CLI: stdin, background output, exit codes, snake_case JSON, doctor * **Breaking for scripts that read `--json`**: every key is now snake_case (`sandbox_id`, `template_id`, `exit_code`, `api_url`), as in the MCP server. `jq -r .sandboxID` becomes `jq -r .sandbox_id`. Errors are `{"error":{"message","exit_code","status","error_code","request_id"}}`. * **Exit codes**: `exec` and `run` pass the remote command's exit code through unchanged and exit 125 when the CLI itself fails, so a remote 2, 3 or 4 no longer looks like a usage, sign-in or not-found error. Other commands keep 1-5. See [Output and exit codes](/docs/cli/overview#output-and-exit-codes). * `exec -i` and `run -i` send stdin to the command. Without `-i`, a piped stdin now gets a warning instead of being dropped silently. * `exec -b` keeps the command's output in the sandbox: `anona-compute output ` prints it (`-f` follows it) and `anona-compute ps ` lists processes. * `anona-compute doctor` checks the configuration, the credential, the gateway and the built-in templates. `template list --all` lists the built-in templates next to yours. `timeout never` removes a sandbox's deadline. `--version` works on the root command. * Checked before anything is sent: `template build --cpu/--memory`, `view --ttl`, `preview --ttl`, `mcp --http`, and a desktop view of a sandbox without a desktop. `login --with-api-key` verifies the key it saves; `config get api_key` masks it unless `--reveal`. * The npm package's wrapper no longer dies before the CLI on Ctrl-C, so `logs -f` exits 0 and `run` prints its summary. **2026-10-31** Delete, not Kill ## "Kill" is now "Delete" * The dashboard, the CLI and these docs say **Delete** where they said Kill. `anona-compute delete` is the command; `anona-compute kill` and `rm` still work, and the JSON they print is unchanged. * Nothing in the API changed: the E2B-compatible `DELETE /sandboxes/{id}`, the SDK's `kill()`, the MCP tool `kill_sandbox` and the `sandbox.lifecycle.killed` webhook event keep their names, so existing code runs as before. **2026-10-30** Fork ## Fork a running sandbox * **Fork**: copy a running sandbox, with its memory, files and running processes, into up to 20 new sandboxes (`POST /sandboxes/{id}/fork`, the stock E2B SDK's `fork`, `anona-compute fork`, and **Fork** on the dashboard's sandbox page - the raw API accepts up to 100, but the SDK, CLI and dashboard all cap at 20). The original is frozen only while its memory delta is written - about 0.1 s - and then keeps running with the same ID and deadline. * Each fork is a new sandbox: it takes a slot of your concurrent-sandbox limit, inherits the original's template, metadata, timeout policy and network policy, and is billed like any other sandbox. A batch larger than your plan has room for creates the forks that fit and reports the reason for each of the others, rather than failing as a whole. * The dashboard's dialog asks how many copies and how long they live, prices the batch from your own rates before you commit, and lists the outcome of every copy. See [Fork](/docs/concepts/lifecycle#fork). **2026-10-29** Custom templates ## Build your own templates * **Template builds**: `anona-compute template build` from a Dockerfile, and the stock E2B SDK's `Template.build` and `e2b` CLI commands, served by the gateway (`/v3/templates`, file uploads, build status, logs, list, get, delete, aliases). Each build runs in its own rootless BuildKit container with no credentials and only proxied egress, gets the Anona runtime layer, and is registered for `create -t `. * **Templates page** in the dashboard: list, build status, build log, delete. MCP tool `list_templates`. * Template, build-concurrency and context-size quotas per organization. **2026-10-28** Preview links, idle pause ## Preview links, public ports, pause when idle * **Preview links**: signed, expiring links to one port of a sandbox (`anona-compute preview`, `POST /v1/sandboxes/{id}/preview-links`, MCP `get_preview_url`, the dashboard's **Share preview**), revocable at once. * **Public ports**: make one port public without opening the rest (`anona-compute preview --public`). * **Pause when idle**: a sandbox pauses itself after a set time with no traffic, sessions or processes (`PUT /v1/sandboxes/{id}/auto-pause`, `autoPause: {"idleMinutes": n}` on create, or the dashboard's **No limit (pauses when idle)**). **2026-10-28** Webhooks, telemetry, DOM view ## Webhooks, OpenTelemetry export, DOM live view, thumbnails * **Webhooks**: signed (Standard Webhooks) callbacks for sandbox lifecycle events, with retries, a delivery log and resend. See [Webhooks and telemetry](/docs/guides/webhooks). * **OpenTelemetry export**: per-sandbox CPU, memory and network metrics and lifecycle spans to your OTLP/HTTP endpoint. * **DOM live view**: the page open in a sandbox's Chrome, replayed in your browser. * **Thumbnails**: a WebP of each sandbox every 3 seconds, on the dashboard and at `GET /v1/sandboxes/{id}/thumbnail`. * New API key scope `integrations:manage` for the webhook and export settings. **2026-10-28** Network, vault, usage ## Network settings, credential vault, usage * **Team egress settings**: the default network policy of new sandboxes, on the dashboard's **Network** page or `GET`/`PUT /v1/network`, with `GET /v1/sandboxes/{id}/network/effective` to see which layer a sandbox's policy came from. * **Change a running sandbox's network**: E2B's `update_network` (`PUT /sandboxes/{id}/network`) now works. * **Credential vault**: store API tokens once and reference them in header rules as `${vault.}`; the egress proxy injects them and the sandbox never sees the value. * **Usage and billing**: `anona-compute usage`, the MCP `get_usage` tool, and `GET /v1/usage` and `/v1/billing` with the new `usage:read` and `billing:read` API key scopes. * **CLI & agent sessions**: a dashboard page lists every machine signed in with `anona-compute login` and revokes them; sign-outs, revocations and role changes now reach the API within seconds. **2026-10-28** Preview ## Developer preview **Sandboxes** * E2B-compatible API: create (v1 and v2), list, get, kill, connect, pause, resume, timeout and refresh, with E2B-shaped errors. Checked with the stock `e2b` SDK 2.20.3, 2.51.0 and 2.61.0. * Long-running sandboxes: `timeout=-1` for no deadline on plans without a maximum lifetime, and pause instead of kill at timeout. * Templates `base`, `python`, `node`, `code-interpreter`, `desktop` and `coding-agent`. * Egress policy at create: plan defaults, allow and deny lists, and a platform floor that always blocks private ranges and cloud metadata. * Every sandbox request passes the gateway, which checks a per-sandbox token. **Access** * Live view of the terminal and the desktop, embeddable in your page, with short-lived viewer tokens and revoke-all. * SSH with 10-minute certificates: `anona-compute ssh`, `scp`, `--print-config` for editors. **Tools** * `anona-compute` CLI: browser sign-in, lifecycle, `exec`, `run`, `connect`, `ssh`, `scp`, `view`, `desktop`, profiles. * `anona-compute mcp`: an MCP server for Claude Code, Codex, Cursor and other clients, over stdio or loopback HTTP. * SDK extras `anona` (Python) and `@anona-labs/compute-sdk` (TypeScript): `sandbox.live` and `sandbox.ssh`. * Dashboard: organizations and roles, scoped API keys with expiry and sandbox lists, sandboxes with live view, usage and billing. ## Coming soon | Area | What | | - | - | | Sandboxes | Named snapshots, sandbox logs and metrics, resume on incoming traffic | | Access | SSH host certificates | | Account | Self-set spend caps, team invitations | | Platform | More regions | # Configuration and profiles Source: https://compute.anonalabs.com/docs/cli/configuration Where the CLI keeps settings and credentials, and the variables it reads. Every setting resolves in this order: the flag, then the environment, then the selected profile in the config file. | Setting | Flag | Environment | Profile key | Default | | - | - | - | - | - | | API key | `--api-key` | `ANONA_COMPUTE_API_KEY`, then `ANONA_API_KEY` (only when it holds an `ac_` or `e2b_` key), then `E2B_API_KEY` | `api_key` | browser sign-in | | Domain | | `ANONA_COMPUTE_DOMAIN`, `ANONA_DOMAIN`, `E2B_DOMAIN` | `domain` | `compute.anonalabs.com` | | API URL | `--api-url` | `ANONA_COMPUTE_API_URL`, `E2B_API_URL` | `api_url` | `https://api.` | | Dashboard URL | `--web-url` (login) | `ANONA_COMPUTE_WEB_URL` | `web_url` | `https://` | | Default template | `-t` | | `default_template` | `base` | | Profile | `--profile` | `ANONA_COMPUTE_PROFILE` | | `default` | Where a cell lists several variables, the first one set wins. Unlike the SDKs, where `E2B_*` always wins, the CLI prefers its own names. A few more variables change one behaviour each: | Variable | Effect | | - | - | | `ANONA_COMPUTE_NO_BROWSER` | Any value: `login` prints the sign-in URL without opening a browser (as `--no-browser`) | | `ANONA_COMPUTE_SANDBOX_URL`, `E2B_SANDBOX_URL` | Send the CLI's `envd` calls (`exec`, `run`, `ps`, `output`, `scp`, the MCP server's tools) to this URL instead of the sandbox's own `envd` host; for local testing | | `ANONA_COMPUTE_MCP_TOKEN` | The bearer token `mcp --http` requires; see [MCP](/docs/guides/mcp) | ```bash cli_config.sh anona-compute config set default_template python anona-compute config get default_template anona-compute --profile staging config set domain compute.anonalabs.com anona-compute config list # every profile; API keys are masked ``` ## Files | What | Where | | - | - | | Settings | `$XDG_CONFIG_HOME/anona-compute/config.toml` (usually `~/.config/anona-compute/config.toml`; `ANONA_COMPUTE_CONFIG` overrides), mode 0600 | | Browser sign-in secret | The OS keychain (macOS Keychain, Windows Credential Manager, Secret Service on Linux), else `credentials.json` (mode 0600) next to `config.toml`. `ANONA_COMPUTE_CREDENTIAL_STORE=file` or `keyring` forces one | | SSH keys for `anona-compute ssh` | `$XDG_RUNTIME_DIR/anona-compute/ssh/`, ephemeral | The browser sign-in keeps a dashboard session for the machine (shown on the dashboard's **CLI & agent sessions** page as `CLI on `) and trades it for an API token that lasts 15 minutes. Signing out, revoking the session on that page, removal from the organization and role changes reach the API within seconds, also for tokens already issued; after a role change the CLI (and a running MCP server) fetches a new token on its own. The CLI never reads Anona Memory's settings or keys, and never sends an Anona Memory key to the compute API. # anona-compute CLI Source: https://compute.anonalabs.com/docs/cli/overview Sign in, manage sandboxes, run commands, SSH, live view and an MCP server for agents. `anona-compute` is one static binary for Linux, macOS and Windows (amd64 and arm64). It is called `anona-compute` because `anona` is the Anona Memory CLI; the two have separate sign-ins and settings. ## Install ```bash install_cli.sh npm install -g @anona-labs/anona-compute # needs Node.js; installs the native binary for your platform anona-compute version ``` The npm package is a small launcher that runs the native binary for your platform. Without Node.js, use either of these instead: * **Download the binary** from the [releases page](https://github.com/anonalabs/anona-compute-sdk/releases) (releases tagged `cli-v`). Each platform has an archive holding the single `anona-compute` binary: `.tar.gz` for Linux and macOS, `.zip` for Windows. `SHA256SUMS` lists their checksums. Unpack it and put `anona-compute` on your `PATH`: ```text sha256sum -c SHA256SUMS --ignore-missing # macOS: shasum -a 256 -c SHA256SUMS --ignore-missing tar -xzf anona-compute__linux_amd64.tar.gz sudo install anona-compute /usr/local/bin/ ``` * **Build it with Go** 1.26 or newer. The source is in the public [anona-compute-sdk](https://github.com/anonalabs/anona-compute-sdk) repository, under `cli/`: ```text go install github.com/anonalabs/anona-compute-sdk/cli/cmd/anona-compute@latest ``` The binary goes to `$(go env GOPATH)/bin`; make sure that is on your `PATH`. ## Sign in ```text anona-compute login # browser sign-in (device code); --no-browser prints the URL only anona-compute whoami # user, organization, role anona-compute logout # revokes this machine's session on the dashboard ``` Or use an API key, which wins over a browser sign-in: ```bash cli_key.sh printenv ANONA_API_KEY | anona-compute login --with-api-key # saves it in the profile anona-compute whoami anona-compute list # reads ANONA_API_KEY; or pass --api-key ``` ## A tour ```bash cli_tour.sh SANDBOX_ID=$(anona-compute create -t base --timeout 30m --json | jq -r .sandbox_id) anona-compute list anona-compute info "$SANDBOX_ID" anona-compute exec "$SANDBOX_ID" -- 'echo hello > /tmp/x && cat /tmp/x' anona-compute timeout "$SANDBOX_ID" 1h anona-compute pause "$SANDBOX_ID" anona-compute resume "$SANDBOX_ID" anona-compute view "$SANDBOX_ID" --mode terminal --control anona-compute delete "$SANDBOX_ID" ``` | Task | Commands | | - | - | | Lifecycle | [`create`](/docs/cli/reference/create), [`list`](/docs/cli/reference/list), [`info`](/docs/cli/reference/info), [`pause`](/docs/cli/reference/pause), [`resume`](/docs/cli/reference/resume), [`timeout`](/docs/cli/reference/timeout), [`fork`](/docs/cli/reference/fork), [`delete`](/docs/cli/reference/delete) | | Run things | [`exec`](/docs/cli/reference/exec), [`run`](/docs/cli/reference/run), [`output`](/docs/cli/reference/output), [`ps`](/docs/cli/reference/ps), [`connect`](/docs/cli/reference/connect), [`logs`](/docs/cli/reference/logs) | | Access | [`ssh`](/docs/cli/reference/ssh), [`scp`](/docs/cli/reference/scp), [`view`](/docs/cli/reference/view), [`desktop`](/docs/cli/reference/desktop), [`preview`](/docs/cli/reference/preview) | | Agents | [`mcp`](/docs/cli/reference/mcp) | | Credentials and idle pause | [`vault`](/docs/cli/reference/vault), [`idle-pause`](/docs/cli/reference/idle-pause) | | Account | [`login`](/docs/cli/reference/login), [`logout`](/docs/cli/reference/logout), [`whoami`](/docs/cli/reference/whoami), [`doctor`](/docs/cli/reference/doctor), [`usage`](/docs/cli/reference/usage), [`config`](/docs/cli/reference/config) | | Templates | [`template build`](/docs/cli/reference/template-build), [`list`](/docs/cli/reference/template-list), [`info`](/docs/cli/reference/template-info), [`logs`](/docs/cli/reference/template-logs), [`delete`](/docs/cli/reference/template-delete) | | Coming soon | [`keys`](/docs/cli/reference/keys), [`limits`](/docs/cli/reference/limits), [`push`](/docs/cli/reference/push), [`recover`](/docs/cli/reference/recover) | `sandbox` (alias `sbx`) groups the lifecycle commands: `anona-compute sbx ls` is `anona-compute list`. ## Output and exit codes `--json` (or `-o json`) prints JSON on stdout; messages go to stderr. A list command (`list`, `ps`, `template list`, `config list`) prints one JSON array, `[]` when there is nothing to list, so `jq -r '.[].sandbox_id'` reads it at any length; every other command prints one JSON object per line. Every key is snake_case (`sandbox_id`, `template_id`, `exit_code`), as in the MCP server's tools. An error is one object on stderr: `{"error":{"message":…,"exit_code":…}}`, plus `status`, `error_code` and `request_id` when known, and `"outcome_unknown": true` when a request that creates something failed in a way that does not say whether it was carried out (see [Retries](#retries)). | Exit code | Meaning | | - | - | | 0 | success | | 1 | general error | | 2 | usage error: a bad flag, argument or value | | 3 | not signed in, or the credential was refused | | 4 | not found | | 5 | a quota, rate or plan limit (`plan_limit_exceeded`; from CLI 0.4.0, also when the API answers `403`) | `exec` and `run` exit with the remote command's own exit code, unchanged, so the CLI composes in shell scripts and CI; when the CLI itself fails they exit 125 (as `docker run` does), and the `--json` error keeps the detailed code in `cli_code`. `connect` exits with the shell's exit code. `anona-compute doctor` checks the configuration, the credential and the connection when something does not work. ## Retries The CLI retries a request at most three times and for at most about a minute, waiting `Retry-After` seconds when the response gives them and backing off otherwise. * A `Should-Retry` header decides on its own: `true` retries, `false` never does. * Without it, a `429` is retried, since it is refused before anything happens. * Without it, a `502`, `503` or `504` is retried for reads, deletes and requests that can safely arrive twice (pause, resume, `timeout`, revoking links). * Without it, a `502`, `503` or `504` is **not** retried for a request that creates something: `create`, `fork`, a template build, a preview link or a vault secret. Such a response comes from something in front of the API, which cannot know whether the sandbox was already started, and a second create could start a second, billed sandbox. The command fails saying so; list your sandboxes before trying again. The API's own errors on create always carry `Should-Retry`, so a create still waits out a `503` while the platform starts or has no capacity yet. `create` and `resume` wait longer than that while the platform has no capacity yet: a `503` with `Should-Retry: true` and `error_code` `sandbox_capacity_unavailable` (a host is starting), `sandbox_engine_starting` (the platform is waking) or `sandbox_size_preparing` (a template is being prepared at a new size) is retried for up to `--capacity-wait`, 10 minutes by default (`ANONA_COMPUTE_CAPACITY_WAIT`; `0` keeps only the short budget above). Each wait follows `Retry-After`, held between 1 and 30 seconds with a little jitter, and prints a line on stderr, so `--json` output stays clean: ```text anona-compute: waiting for capacity: no host has room yet; a host may be starting, retrying in 30s (1m0s elapsed) ``` `resume --capacity-wait`, the 1 to 30 second bounds and `sandbox_size_preparing` need CLI 0.4.0 or later; 0.3.x waits on `create` only. # anona-compute Source: https://compute.anonalabs.com/docs/cli/reference/anona-compute Manage Anona Compute sandboxes from the terminal ```text anona-compute manages Anona Compute sandboxes through the E2B-compatible API. Configuration comes from flags, then the environment (the API key from ANONA_COMPUTE_API_KEY, then ANONA_API_KEY when it holds an ac_ or e2b_ key, then E2B_API_KEY; ANONA_COMPUTE_DOMAIN or E2B_DOMAIN, ANONA_COMPUTE_API_URL or E2B_API_URL), then the profile in $XDG_CONFIG_HOME/anona-compute/config.toml. anona-compute doctor checks the whole chain. JSON output: --json (or -o json) prints JSON on stdout. A list command (list, ps, template list, config list) prints one array, [] when there is nothing to list; other commands print one object per line. Every key is snake_case (sandbox_id, template_id, cpu_count, api_url), as in the MCP server's tools; keys inside metadata, envs and log fields are yours and are printed as given. An error is one object on stderr: {"error":{"message":"...","exit_code":N,"status":404, "error_code":"...","request_id":"..."}} status, error_code and request_id appear when known; a failure with no HTTP answer has error_code "network_error" or "timeout". Exit codes: 0 success 1 general error 2 usage error (bad flag, argument or value) 3 not signed in, or the credential was refused (HTTP 401/403) 4 not found (HTTP 404) 5 plan limit or rate limit (HTTP 429, or error_code plan_limit_exceeded) exec and run pass the remote command's exit status through unchanged (0-255; 130 after Ctrl-C) and exit 125 when anona-compute itself failed, for any of the reasons 1-5 above; their --json error keeps that detailed code in "cli_code". ``` ## Usage ```text anona-compute [flags] anona-compute [command] ``` ## Commands | Command | Description | | - | - | | [`config`](/docs/cli/reference/config) | Read and write profile settings | | [`connect`](/docs/cli/reference/connect) | Open an interactive shell in a sandbox | | [`create`](/docs/cli/reference/create) | Create sandboxes | | [`delete`](/docs/cli/reference/delete) | Delete sandboxes | | [`desktop`](/docs/cli/reference/desktop) | Open a sandbox desktop | | [`doctor`](/docs/cli/reference/doctor) | Check the configuration, credentials and connection to Anona Compute | | [`exec`](/docs/cli/reference/exec) | Run a command in a sandbox | | [`fork`](/docs/cli/reference/fork) | Fork a running sandbox into new sandboxes | | [`idle-pause`](/docs/cli/reference/idle-pause) | Pause a sandbox once nothing has used it for a while | | [`info`](/docs/cli/reference/info) | Show one sandbox | | [`keys`](/docs/cli/reference/keys) | Manage API keys (not available yet) | | [`limits`](/docs/cli/reference/limits) | Show plan limits and usage (not available yet) | | [`list`](/docs/cli/reference/list) | List sandboxes | | [`login`](/docs/cli/reference/login) | Sign in through the browser (or save an API key with --with-api-key) | | [`logout`](/docs/cli/reference/logout) | Sign out: revoke the CLI session on the dashboard and remove local credentials | | [`logs`](/docs/cli/reference/logs) | Show sandbox logs | | [`mcp`](/docs/cli/reference/mcp) | Run an MCP server so AI agents can use Anona Compute | | [`output`](/docs/cli/reference/output) | Print the output of a command started with exec --background | | [`pause`](/docs/cli/reference/pause) | Pause a sandbox | | [`preview`](/docs/cli/reference/preview) | Share a sandbox port with a signed preview link | | [`ps`](/docs/cli/reference/ps) | List the processes running in a sandbox | | [`push`](/docs/cli/reference/push) | Push a git working tree into a sandbox (not available yet) | | [`recover`](/docs/cli/reference/recover) | Recover a sandbox from its last snapshot (not available yet) | | [`rename`](/docs/cli/reference/rename) | Name a sandbox, or remove its name | | [`resume`](/docs/cli/reference/resume) | Resume a paused sandbox | | [`run`](/docs/cli/reference/run) | Create a sandbox, run one command, then delete the sandbox | | [`sandbox`](/docs/cli/reference/sandbox) | Sandbox commands (same as the top-level create, list, info, ...) | | [`scp`](/docs/cli/reference/scp) | Copy files to or from a sandbox over SSH | | [`ssh`](/docs/cli/reference/ssh) | SSH into a sandbox | | [`template`](/docs/cli/reference/template) | Build and manage templates | | [`timeout`](/docs/cli/reference/timeout) | Set how long a sandbox lives from now | | [`usage`](/docs/cli/reference/usage) | Show usage and cost for a billing period | | [`vault`](/docs/cli/reference/vault) | Store credentials the sandbox never sees | | [`version`](/docs/cli/reference/version) | Print the CLI version | | [`view`](/docs/cli/reference/view) | Open a live view of a sandbox | | [`whoami`](/docs/cli/reference/whoami) | Show who the CLI is signed in as | ## Flags | Flag | Type | Description | | - | - | - | | `--api-key` | string | API key (env ANONA_COMPUTE_API_KEY, ANONA_API_KEY, E2B_API_KEY) | | `--api-url` | string | API URL (env ANONA_COMPUTE_API_URL, E2B_API_URL; default [https://api.\<E2B_DOMAIN](https://api.\<E2B_DOMAIN)>) | | `--help`, `-h` | | help for anona-compute | | `--json` | | JSON output on stdout (same as -o json) | | `--output`, `-o` | string | output format: text or json (default "text") | | `--profile` | string | config profile to use (env ANONA_COMPUTE_PROFILE; default "default") | | `--request-timeout` | duration | timeout for each API request (0 = none) | | `--verbose`, `-v` | | verbose output on stderr | | `--version` | | print the CLI version (same as the version command) | # anona-compute config Source: https://compute.anonalabs.com/docs/cli/reference/config Read and write profile settings ```text Read and write settings of the selected profile (--profile, default "default"). Keys: api_url, api_key, domain, default_template, web_url. The file is written with mode 0600. ``` ## Usage ```text anona-compute config [flags] anona-compute config [command] ``` ## Commands | Command | Description | | - | - | | [`config get`](/docs/cli/reference/config-get) | Print one setting (api_key is masked unless --reveal) | | [`config list`](/docs/cli/reference/config-list) | List every profile and its settings (API keys are masked) | | [`config set`](/docs/cli/reference/config-set) | Change one setting | ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for config | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute config get Source: https://compute.anonalabs.com/docs/cli/reference/config-get Print one setting (api_key is masked unless --reveal) ```text Print one setting (api_key is masked unless --reveal) ``` ## Usage ```text anona-compute config get KEY [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for get | | `--reveal` | | print the API key itself instead of a masked one | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute config list Source: https://compute.anonalabs.com/docs/cli/reference/config-list List every profile and its settings (API keys are masked) ```text List every profile and its settings (API keys are masked) ``` ## Usage ```text anona-compute config list [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for list | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute config set Source: https://compute.anonalabs.com/docs/cli/reference/config-set Change one setting ```text Change one setting ``` ## Usage ```text anona-compute config set KEY VALUE [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for set | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute connect Source: https://compute.anonalabs.com/docs/cli/reference/connect Open an interactive shell in a sandbox ```text Open an interactive login shell (/bin/bash -i -l) on a PTY through envd, the same channel the E2B SDK's sandbox.pty uses; no sshd is needed. The local terminal is put in raw mode and resizes follow it. Type Ctrl-] then d to detach (the shell keeps running). anona-compute exits with the shell's exit code. ``` ## Usage ```text anona-compute connect SANDBOX_ID [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--cwd`, `-w` | string | working directory | | `--help`, `-h` | | help for connect | | `--user`, `-u` | string | user to run the shell as (default: the sandbox's default user) | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute create Source: https://compute.anonalabs.com/docs/cli/reference/create Create sandboxes ```text Create one or more sandboxes (POST /v2/sandboxes) and print their IDs. --size picks the sandbox's vCPU, memory and disk: small, medium, large or xl. Every template has a minimum size, and a size below it, or one your plan does not include, is refused with the sizes that would work (`anona-compute template info` lists them). A template your team built has its own vCPU, memory and disk as its minimum. A built-in template's minimum is set for it instead: small for base, python, node and code-interpreter, medium for desktop and agent-desktop. Without --size the sandbox runs at the template's own size (on Free, the smallest size the template allows: small for base). The first sandbox at a size a template was not built at takes longer while that size is prepared. A create is retried only when the server says it is safe (Should-Retry: true, waiting Retry-After). When the server has no capacity yet (a host is starting, or the sandbox server is waking), a create waits up to --capacity-wait (10 minutes by default) and prints a progress line on stderr each time it retries. A 502, 503 or 504 without that header is not retried, because the sandbox may already have started: the command fails saying so, and you should list your sandboxes before creating again. With --count, up to --parallel creates run at once and each has its own --create-timeout, so one slow or failing create does not hold up the others. Each sandbox is printed as it starts; failures are reported on stderr with a summary, and the command exits non-zero if any create failed. ``` ## Usage ```text anona-compute create [flags] ``` **Aliases:** `create`, `new` ## Flags | Flag | Type | Description | | - | - | - | | `--allow-out` | stringArray | host the sandbox may reach (repeatable); with --no-internet this is the allow-list | | `--auto-pause` | | pause instead of delete when the timeout ends | | `--capacity-wait` | duration | how long a create waits while the server has no capacity yet, e.g. a host is starting (0 = do not wait; env ANONA_COMPUTE_CAPACITY_WAIT) (default 10m0s) | | `--count` | int | number of sandboxes to create (1-100) (default 1) | | `--create-timeout` | duration | give up on one create after this long, waits for capacity included (default 15m0s) | | `--env`, `-e` | stringArray | environment variable KEY=VALUE for the sandbox (repeatable) | | `--fail-fast` | | with --count, stop at the first failure | | `--help`, `-h` | | help for create | | `--idle-pause` | string | pause the sandbox after this long with nothing using it (e.g. 15m, 1h); "off" disables it. A duration also makes the timeout pause the sandbox instead of deleting it, as --auto-pause does | | `--metadata` | stringArray | metadata KEY=VALUE (repeatable) | | `--name` | string | a name for the sandbox, shown beside its ID (stored as metadata name=NAME; the ID stays the identifier) | | `--network-file` | string | JSON egress policy for the sandbox ("-" reads stdin); replaces the flags above | | `--no-internet` | | create the sandbox without internet access | | `--parallel` | int | with --count, how many creates run at once (1-20) (default 4) | | `--size` | string | sandbox size: small (1 vCPU, 2 GiB, 10 GB disk), medium (2, 4 GiB, 20 GB), large (4, 8 GiB, 40 GB) or xl (8, 16 GiB, 80 GB); default: the template's own size (on Free, the smallest size the template allows) | | `--template`, `-t` | string | template ID or alias (default: profile default_template, else "base") | | `--timeout` | string | sandbox lifetime before it is deleted or paused (e.g. 300s, 1h), or "never" for no time limit (default "300s") | | `--vault-inject` | stringArray | inject a vault secret into requests to a host: HOST:HEADER=\[bearer:\|basic:]SECRET (repeatable) | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute delete Source: https://compute.anonalabs.com/docs/cli/reference/delete Delete sandboxes ```text Delete sandboxes ``` ## Usage ```text anona-compute delete SANDBOX_ID... [flags] ``` **Aliases:** `delete`, `kill`, `rm` ## Flags | Flag | Type | Description | | - | - | - | | `--all` | | delete every running and paused sandbox | | `--help`, `-h` | | help for delete | | `--yes` | | confirm --all | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute desktop Source: https://compute.anonalabs.com/docs/cli/reference/desktop Open a sandbox desktop ```text Reach the desktop of a sandbox (desktop template). anona-compute desktop ID print the live-view URL (control) anona-compute desktop ID --vnc 127.0.0.1:5901 serve the desktop as plain VNC (RFB) on a local port for any VNC client; each client gets its own session through the relay anona-compute desktop ID --mode novnc print the E2B-compatible noVNC URL on port 6080 (started by the e2b-desktop SDK) ``` ## Usage ```text anona-compute desktop SANDBOX_ID [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--force` | | go ahead even if the sandbox's template has no desktop | | `--help`, `-h` | | help for desktop | | `--mode` | string | live (Anona relay) or novnc (E2B noVNC URL) (default "live") | | `--view-only` | | with --vnc: view scope (the sandbox serves a view-only VNC server) | | `--vnc` | string | serve the desktop as VNC on this local address (for example 127.0.0.1:5901) | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute doctor Source: https://compute.anonalabs.com/docs/cli/reference/doctor Check the configuration, credentials and connection to Anona Compute ```text Check, one line each, everything a command needs, and say what is wrong: config which profile and config file are used, and where the credential comes from (--api-key, ANONA_COMPUTE_API_KEY, ANONA_API_KEY or E2B_API_KEY, the config file, or a browser login in the keychain or credentials.json) api the gateway answers at the API URL (GET /healthz), and how fast auth the gateway accepts the credential (as whoami checks it) templates the built-in templates can be listed from the template catalog ssh the ssh binary is on PATH (needed by ssh, scp and the MCP ssh tool) Each check is ok, warn or fail; a check that cannot run because an earlier one failed is skip. Exit 0 when nothing failed, 1 otherwise. --json prints one object per check: {"check","status","detail","latency_ms"?}. ``` ## Usage ```text anona-compute doctor [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for doctor | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute exec Source: https://compute.anonalabs.com/docs/cli/reference/exec Run a command in a sandbox ```text Run a command in a running sandbox and stream its output. anona-compute exits with the command's exit code. With one argument the command is a shell string (anona-compute exec ID -- 'ls | wc -l'); several arguments are quoted and joined. The command's stdin is empty unless -i/--stdin is given; with -i the CLI's stdin is streamed to it and closed at EOF: tar -cz src | anona-compute exec -i ID -- 'tar -xz -C /home/user' -b/--background starts the command and prints its PID. Its stdout and stderr are kept in the sandbox (under /tmp/anona-compute-bg); read them with anona-compute output ID PID (-f to follow) and list processes with anona-compute ps ID. With --json, output is one object per line: {"type":"stdout"|"stderr","data":...} and finally {"type":"exit","exit_code":N}. Exit codes: 0 success 1 general error 2 usage error (bad flag, argument or value) 3 not signed in, or the credential was refused (HTTP 401/403) 4 not found (HTTP 404) 5 plan limit or rate limit (HTTP 429, or error_code plan_limit_exceeded) exec and run pass the remote command's exit status through unchanged (0-255; 130 after Ctrl-C) and exit 125 when anona-compute itself failed, for any of the reasons 1-5 above; their --json error keeps that detailed code in "cli_code". ``` ## Usage ```text anona-compute exec SANDBOX_ID -- COMMAND [ARGS...] [flags] ``` **Aliases:** `exec`, `ex` ## Flags | Flag | Type | Description | | - | - | - | | `--background`, `-b` | | start the command, print its PID and return; read its output later with anona-compute output | | `--cmd-timeout` | duration | stop waiting for the command after this long (0 = no limit) | | `--cwd`, `-w` | string | working directory | | `--env`, `-e` | stringArray | environment variable KEY=VALUE for the command (repeatable) | | `--help`, `-h` | | help for exec | | `--stdin`, `-i` | | send this terminal's stdin to the command (closed at EOF) | | `--user`, `-u` | string | user to run as (default: the sandbox's default user) | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute fork Source: https://compute.anonalabs.com/docs/cli/reference/fork Fork a running sandbox into new sandboxes > [!NOTE] > > Forking freezes the sandbox for a moment while its memory is written (about 0.1 s), then it keeps running with the same ID and lifetime. Each fork is a new sandbox: it counts towards your concurrent-sandbox limit and is billed like any other. `--count` above what your plan has room for is not an error for the whole batch - the forks that fit are made and the rest are reported one by one. ```text Fork a sandbox (POST /sandboxes/{id}/fork): checkpoint it with its memory and start --count new sandboxes from that checkpoint. Prints one line per fork. Like create, a fork is not retried on a 502, 503 or 504 unless the server says Should-Retry: true, because the forks may already exist: list your sandboxes before forking again. ``` ## Usage ```text anona-compute fork SANDBOX_ID [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--count` | int | number of forks (1-20) (default 1) | | `--help`, `-h` | | help for fork | | `--timeout` | string | lifetime of each fork (empty = server default, 15s in the E2B spec) (default "300s") | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute idle-pause Source: https://compute.anonalabs.com/docs/cli/reference/idle-pause Pause a sandbox once nothing has used it for a while ```text Set a sandbox's idle-pause time (PUT /v1/sandboxes/{id}/auto-pause). The sandbox pauses once nothing has used it for DURATION, however much time its timeout has left. DURATION is a whole number of minutes (15m, 1h, up to 7 days); "off" turns idle pausing off. This is not --auto-pause, which decides what happens when the TIMEOUT runs out. A sandbox can have both. What counts as use, restarting the clock: a request to any of the sandbox's ports (except envd's /health), an open terminal, live view, SSH session or byte pipe, and any process envd started that is still running. CPU the guest burns on its own does not count, so a sandbox busy on work it started itself still pauses. Resume it with "anona-compute resume SANDBOX_ID". ``` ## Usage ```text anona-compute idle-pause SANDBOX_ID DURATION [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for idle-pause | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute info Source: https://compute.anonalabs.com/docs/cli/reference/info Show one sandbox ```text Show one sandbox ``` ## Usage ```text anona-compute info SANDBOX_ID [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for info | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute keys Source: https://compute.anonalabs.com/docs/cli/reference/keys Manage API keys (not available yet) > [!WARNING] > > **Coming soon.** This command is a placeholder: it prints what it needs and exits 1. ```text Manage API keys (not available yet) ``` ## Usage ```text anona-compute keys [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for keys | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute limits Source: https://compute.anonalabs.com/docs/cli/reference/limits Show plan limits and usage (not available yet) > [!WARNING] > > **Coming soon.** This command is a placeholder: it prints what it needs and exits 1. ```text Show plan limits and usage (not available yet) ``` ## Usage ```text anona-compute limits [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for limits | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute list Source: https://compute.anonalabs.com/docs/cli/reference/list List sandboxes ```text List sandboxes ``` ## Usage ```text anona-compute list [flags] ``` **Aliases:** `list`, `ls` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for list | | `--limit` | int | show at most N sandboxes (0 = all) | | `--metadata` | stringArray | only sandboxes with metadata KEY=VALUE (repeatable) | | `--name` | string | only sandboxes with this exact name (same as --metadata name=NAME) | | `--state`, `-s` | string | running, paused or all (default "running") | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute login Source: https://compute.anonalabs.com/docs/cli/reference/login Sign in through the browser (or save an API key with --with-api-key) ```text Sign in to Anona Compute. Without flags, anona-compute login starts a device sign-in (RFC 8628): it prints a URL and a code, opens the browser, and waits while you sign in to the dashboard, check the code, pick the organization and approve. The CLI then holds a dashboard session for this machine and trades it for gateway tokens that last 15 minutes. The session secret is stored in the OS keychain when one is available, else in credentials.json (mode 0600) next to config.toml; ANONA_COMPUTE_CREDENTIAL_STORE=file|keyring forces one. anona-compute logout revokes it. --with-api-key reads an API key (ac_ + 40 lowercase hex characters) from stdin, saves it to the profile, and checks it against the gateway (an invalid key is still saved, and the command exits 3; --no-verify skips the check). The dashboard is --web-url, else ANONA_COMPUTE_WEB_URL, else the profile's web_url, else https://. ``` ## Usage ```text anona-compute login [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for login | | `--no-browser` | | print the sign-in URL but do not open a browser | | `--no-verify` | | with --with-api-key: save the key without checking it against the gateway | | `--org` | string | organization slug to act in (default: the one picked in the browser) | | `--web-url` | string | dashboard URL (env ANONA_COMPUTE_WEB_URL; default https\://\) | | `--with-api-key` | | read an API key from stdin instead of signing in through the browser | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute logout Source: https://compute.anonalabs.com/docs/cli/reference/logout Sign out: revoke the CLI session on the dashboard and remove local credentials ```text Sign out of the selected profile. A browser login's session is deleted on the dashboard first (gateway tokens already issued from it stop working within seconds), then removed from the keychain or credentials file. An API key saved with --with-api-key is removed from the profile (revoke the key itself in the dashboard). ``` ## Usage ```text anona-compute logout [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for logout | | `--local` | | only remove local credentials; do not contact the dashboard | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute logs Source: https://compute.anonalabs.com/docs/cli/reference/logs Show sandbox logs ```text Show sandbox logs (GET /v2/sandboxes/{id}/logs), oldest first. --follow keeps polling for new lines until the sandbox ends or you press Ctrl-C (exit 0). ``` ## Usage ```text anona-compute logs SANDBOX_ID [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--follow`, `-f` | | keep printing new lines | | `--help`, `-h` | | help for logs | | `--level` | string | minimum level: debug, info, warn or error | | `--search` | string | only lines containing this text (case-sensitive) | | `--since` | string | only lines newer than this (e.g. 10m, 1h) | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute mcp Source: https://compute.anonalabs.com/docs/cli/reference/mcp Run an MCP server so AI agents can use Anona Compute ```text Serve the Model Context Protocol so AI agents (Claude Code, Codex, Cursor and other MCP clients) can create sandboxes, run commands, move files and delete sandboxes with this CLI's credentials (anona-compute login, or an API key). By default the server speaks MCP over stdio; the agent starts it: claude mcp add anona-compute -- anona-compute mcp codex mcp add anona-compute -- anona-compute mcp --http 127.0.0.1:8765 serves streamable HTTP at http://127.0.0.1:8765/mcp instead. Only loopback addresses are allowed, and every request must carry Authorization: Bearer , where the token is ANONA_COMPUTE_MCP_TOKEN or a random one printed on stderr at start. Every tool call goes through the gateway with your credential, so it can do exactly what you can. A viewer (or --read-only) gets the read-only tools only. ``` ## Usage ```text anona-compute mcp [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for mcp | | `--http` | string | serve streamable HTTP on this loopback address (for example 127.0.0.1:8765) instead of stdio | | `--read-only` | | offer only the tools that do not change sandboxes | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute output Source: https://compute.anonalabs.com/docs/cli/reference/output Print the output of a command started with exec --background ```text Print the stdout and stderr of a command started with anona-compute exec -b, which keeps them in the sandbox under /tmp/anona-compute-bg. stdout goes to stdout and stderr to stderr; a line on stderr says whether the process is still running or how it exited. anona-compute exec -b ID -- 'npm run dev' prints the PID anona-compute output ID PID everything so far anona-compute output ID PID -f follow until the process ends With --json: one object {"pid","state","exit_code"?,"stdout","stderr"}; with -f, {"type":"stdout"|"stderr","data"} lines and a final {"type":"exit",...}. Processes started any other way have no saved output (anona-compute ps lists them). ``` ## Usage ```text anona-compute output SANDBOX_ID PID [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--follow`, `-f` | | keep printing output until the process ends | | `--help`, `-h` | | help for output | | `--user`, `-u` | string | user to read the output as (default: the sandbox's default user) | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute pause Source: https://compute.anonalabs.com/docs/cli/reference/pause Pause a sandbox > [!NOTE] > > `--mode filesystem` is refused by the gateway: filesystem-only snapshots are not available, so pause always keeps memory. ```text Pause a sandbox (POST /sandboxes/{id}/pause). Memory and disk are kept, so running processes continue after resume. --mode filesystem (keep only the disk; resume cold-boots) is not yet supported: the platform has no disk-only pause, and it is refused. ``` ## Usage ```text anona-compute pause SANDBOX_ID [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for pause | | `--mode` | string | full (memory and disk); filesystem (disk only) is not yet supported (default "full") | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute preview Source: https://compute.anonalabs.com/docs/cli/reference/preview Share a sandbox port with a signed preview link ```text Print a shareable link to one port of a sandbox, for example a dev server on 3000. Anyone with the link can open that port in a browser until it expires (--ttl, default 1h, at most 24h): the sandbox edge exchanges it for a cookie scoped to that port's host. Other ports and envd stay private. anona-compute preview 3000 anona-compute preview 3000 --ttl 15m anona-compute preview --revoke end every link (and live-view token) of the sandbox anona-compute preview 3000 --public serve the port to anyone, no link needed anona-compute preview 3000 --private back to links only ``` ## Usage ```text anona-compute preview SANDBOX_ID [PORT] [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for preview | | `--private` | | make the port private again | | `--public` | | make the port public instead of printing a link | | `--revoke` | | revoke every preview link and live-view token of the sandbox | | `--ttl` | duration | link lifetime, 1m to 24h (default 1h) | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute ps Source: https://compute.anonalabs.com/docs/cli/reference/ps List the processes running in a sandbox ```text List the processes envd started in a sandbox that are still running (exec, exec -b, connect shells, SDK commands). OUTPUT is "saved" for commands started with anona-compute exec -b, whose output anona-compute output ID PID prints. ``` ## Usage ```text anona-compute ps SANDBOX_ID [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for ps | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute push Source: https://compute.anonalabs.com/docs/cli/reference/push Push a git working tree into a sandbox (not available yet) > [!WARNING] > > **Coming soon.** This command is a placeholder: it prints what it needs and exits 1. ```text Push a git working tree into a sandbox (not available yet) ``` ## Usage ```text anona-compute push [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for push | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute recover Source: https://compute.anonalabs.com/docs/cli/reference/recover Recover a sandbox from its last snapshot (not available yet) > [!WARNING] > > **Coming soon.** This command is a placeholder: it prints what it needs and exits 1. ```text Recover a sandbox from its last snapshot (not available yet) ``` ## Usage ```text anona-compute recover [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for recover | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute rename Source: https://compute.anonalabs.com/docs/cli/reference/rename Name a sandbox, or remove its name ```text Set a sandbox's name (PUT /v1/sandboxes/{id}/name). The name is shown beside the ID in list, info and the console, and is stored as the metadata key "name", so create --name and list --name use the same value. The sandbox ID stays the identifier: every other command still takes the ID. A name is 1 to 64 letters, digits, spaces, dots, dashes or underscores, starting with a letter or digit. --clear removes it. ``` ## Usage ```text anona-compute rename SANDBOX_ID [NAME] [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--clear` | | remove the sandbox's name | | `--help`, `-h` | | help for rename | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute resume Source: https://compute.anonalabs.com/docs/cli/reference/resume Resume a paused sandbox ```text Resume a paused sandbox (POST /v2/sandboxes/{id}/connect). A running sandbox is left running; its timeout is only ever extended. When the server has no capacity yet (a host is starting, or the sandbox server is waking), a resume waits up to --capacity-wait (10 minutes by default) and prints a progress line on stderr each time it retries. ``` ## Usage ```text anona-compute resume SANDBOX_ID [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--capacity-wait` | duration | how long a resume waits while the server has no capacity yet, e.g. a host is starting (0 = do not wait; env ANONA_COMPUTE_CAPACITY_WAIT) (default 10m0s) | | `--help`, `-h` | | help for resume | | `--timeout` | string | minimum lifetime from now; a later deadline is kept (default "300s") | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute run Source: https://compute.anonalabs.com/docs/cli/reference/run Create a sandbox, run one command, then delete the sandbox > [!NOTE] > > Coming soon: per-run cost. The summary on stderr says `cost: unknown` for now. See [Usage and billing](/docs/usage-and-billing) for what your sandboxes used. ```text Create a sandbox, run one command in it, print a summary on stderr, and delete the sandbox (also on error or Ctrl-C). anona-compute exits with the command's exit code; -i/--stdin streams this terminal's stdin to the command. Cost is printed when the API reports it; the current API does not, so the summary says "unknown" rather than guessing. Exit codes: 0 success 1 general error 2 usage error (bad flag, argument or value) 3 not signed in, or the credential was refused (HTTP 401/403) 4 not found (HTTP 404) 5 plan limit or rate limit (HTTP 429, or error_code plan_limit_exceeded) exec and run pass the remote command's exit status through unchanged (0-255; 130 after Ctrl-C) and exit 125 when anona-compute itself failed, for any of the reasons 1-5 above; their --json error keeps that detailed code in "cli_code". ``` ## Usage ```text anona-compute run [flags] -- COMMAND [ARGS...] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--allow-out` | stringArray | host the sandbox may reach (repeatable); with --no-internet this is the allow-list | | `--auto-pause` | | pause instead of delete when the timeout ends | | `--cmd-timeout` | duration | stop waiting for the command after this long (0 = no limit) | | `--cwd`, `-w` | string | working directory | | `--env`, `-e` | stringArray | environment variable KEY=VALUE for the sandbox (repeatable) | | `--help`, `-h` | | help for run | | `--idle-pause` | string | pause the sandbox after this long with nothing using it (e.g. 15m, 1h); "off" disables it. A duration also makes the timeout pause the sandbox instead of deleting it, as --auto-pause does | | `--keep` | | do not delete the sandbox after the command | | `--metadata` | stringArray | metadata KEY=VALUE (repeatable) | | `--name` | string | a name for the sandbox, shown beside its ID (stored as metadata name=NAME; the ID stays the identifier) | | `--network-file` | string | JSON egress policy for the sandbox ("-" reads stdin); replaces the flags above | | `--no-internet` | | create the sandbox without internet access | | `--size` | string | sandbox size: small (1 vCPU, 2 GiB, 10 GB disk), medium (2, 4 GiB, 20 GB), large (4, 8 GiB, 40 GB) or xl (8, 16 GiB, 80 GB); default: the template's own size (on Free, the smallest size the template allows) | | `--stdin`, `-i` | | send this terminal's stdin to the command (closed at EOF) | | `--template`, `-t` | string | template ID or alias (default: profile default_template, else "base") | | `--timeout` | string | sandbox lifetime before it is deleted or paused (e.g. 300s, 1h), or "never" for no time limit (default "300s") | | `--user`, `-u` | string | user to run as (default: the sandbox's default user) | | `--vault-inject` | stringArray | inject a vault secret into requests to a host: HOST:HEADER=\[bearer:\|basic:]SECRET (repeatable) | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute sandbox Source: https://compute.anonalabs.com/docs/cli/reference/sandbox Sandbox commands (same as the top-level create, list, info, ...) ```text Sandbox commands (same as the top-level create, list, info, ...) ``` ## Usage ```text anona-compute sandbox [flags] anona-compute sandbox [command] ``` **Aliases:** `sandbox`, `sbx` ## Commands | Command | Description | | - | - | | [`sandbox create`](/docs/cli/reference/create) | Create sandboxes | | [`sandbox delete`](/docs/cli/reference/delete) | Delete sandboxes | | [`sandbox exec`](/docs/cli/reference/exec) | Run a command in a sandbox | | [`sandbox fork`](/docs/cli/reference/fork) | Fork a running sandbox into new sandboxes | | [`sandbox info`](/docs/cli/reference/info) | Show one sandbox | | [`sandbox list`](/docs/cli/reference/list) | List sandboxes | | [`sandbox logs`](/docs/cli/reference/logs) | Show sandbox logs | | [`sandbox output`](/docs/cli/reference/output) | Print the output of a command started with exec --background | | [`sandbox pause`](/docs/cli/reference/pause) | Pause a sandbox | | [`sandbox ps`](/docs/cli/reference/ps) | List the processes running in a sandbox | | [`sandbox rename`](/docs/cli/reference/rename) | Name a sandbox, or remove its name | | [`sandbox resume`](/docs/cli/reference/resume) | Resume a paused sandbox | | [`sandbox timeout`](/docs/cli/reference/timeout) | Set how long a sandbox lives from now | ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for sandbox | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute scp Source: https://compute.anonalabs.com/docs/cli/reference/scp Copy files to or from a sandbox over SSH ```text Copy files with the system scp through the same certificate and relay as anona-compute ssh. Write sandbox paths with a leading colon: anona-compute scp sbx_123 ./data.csv :/home/user/ anona-compute scp sbx_123 -- -r :/home/user/out ./out ``` ## Usage ```text anona-compute scp SANDBOX_ID [SCP_FLAGS...] SOURCE... TARGET [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for scp | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute ssh Source: https://compute.anonalabs.com/docs/cli/reference/ssh SSH into a sandbox ```text Open an OpenSSH session to a sandbox. anona-compute makes an ephemeral Ed25519 key under $XDG_RUNTIME_DIR/anona-compute/ssh/, has the gateway sign it (a 10-minute certificate for the sandbox user), and runs the system ssh with ProxyCommand "anona-compute ssh --proxy %n", which carries the connection over the stream relay. Arguments after -- go to ssh (a remote command, -L, -R, ...). --print-config prints an ssh_config block, so scp, rsync and editors can use "Host " directly; the certificate in it expires after 10 minutes, so run it again (or anona-compute ssh) to renew. ``` ## Usage ```text anona-compute ssh SANDBOX_ID [-- SSH_ARGS...] [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for ssh | | `--print-config` | | print an ssh_config block for the sandbox instead of connecting | | `--proxy` | | act as the OpenSSH ProxyCommand: pipe stdin/stdout to the sandbox sshd | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute template Source: https://compute.anonalabs.com/docs/cli/reference/template Build and manage templates ```text Build and manage templates ``` ## Usage ```text anona-compute template [flags] anona-compute template [command] ``` **Aliases:** `template`, `templates`, `tpl` ## Commands | Command | Description | | - | - | | [`template build`](/docs/cli/reference/template-build) | Build a template from a Dockerfile | | [`template delete`](/docs/cli/reference/template-delete) | Delete a template (running sandboxes keep running) | | [`template info`](/docs/cli/reference/template-info) | Show a template and its builds | | [`template list`](/docs/cli/reference/template-list) | List your templates (--all: the built-in ones too) | | [`template logs`](/docs/cli/reference/template-logs) | Print a build's log (the newest build unless --build), following it while it runs | ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for template | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute template build Source: https://compute.anonalabs.com/docs/cli/reference/template-build Build a template from a Dockerfile ```text Builds a template from a Dockerfile and a build context (default: the current directory), streaming the build log. The gateway builds it with BuildKit in an isolated builder, adds the Anona runtime (envd), pushes it and registers it; sandboxes then start from it by name: anona-compute template build -f Dockerfile --name my-env anona-compute create -t my-env --cpu, --memory and --disk size every sandbox started from the template: anona-compute template build --name big --cpu 4 --memory 8192 --disk 20480 The disk defaults to 1024 MiB. Your plan caps it, and a build that asks for more is refused with the plan's limit before anything is uploaded. Every FROM image is pinned by digest. EXPOSE 49983 (envd) is refused. The image's CMD runs at sandbox start only when the last stage declares CMD or ENTRYPOINT, or with --start-cmd. .dockerignore in the context is honored. ``` ## Usage ```text anona-compute template build [CONTEXT_DIR] [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--cpu` | int | minimum vCPUs sandboxes from this template need, 1-8 (default 2); a sandbox can use any size that meets it | | `--disk` | int | minimum writable disk sandboxes from this template need, 1024-81920 MiB, up to your plan's limit (default 1024) | | `--file`, `-f` | string | Dockerfile (default CONTEXT_DIR/Dockerfile) | | `--help`, `-h` | | help for build | | `--memory` | int | minimum memory sandboxes from this template need, 128-16384 MiB (default 2048) | | `--name`, `-n` | string | template name (default: the context directory's name) | | `--no-cache` | | build without the build cache | | `--start-cmd` | string | command to run when a sandbox starts (after envd) | | `--tag` | stringArray | tag for this build (repeatable) | | `--wait` | | stream the build log and wait until it is ready (--wait=false returns at once) (default true) | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute template delete Source: https://compute.anonalabs.com/docs/cli/reference/template-delete Delete a template (running sandboxes keep running) ```text Delete a template (running sandboxes keep running) ``` ## Usage ```text anona-compute template delete NAME|TEMPLATE_ID [flags] ``` **Aliases:** `delete`, `rm` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for delete | | `--yes`, `-y` | | confirm the deletion | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute template info Source: https://compute.anonalabs.com/docs/cli/reference/template-info Show a template and its builds ```text Show a template and its builds ``` ## Usage ```text anona-compute template info NAME|TEMPLATE_ID [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for info | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute template list Source: https://compute.anonalabs.com/docs/cli/reference/template-list List your templates (--all: the built-in ones too) ```text List the templates your team built, with their build status and size. SIZE is the image size of a template's current build, which is what counts against your plan's template storage (the build before it is kept for a rollback and not counted). The last line is your team's usage against its plan: templates, and template storage in GiB. Built-in templates never count. --all also lists the built-in templates every team can launch (base, python, node, desktop, ...), from the gateway's template catalog, with a SOURCE column (built-in or custom). Built-in templates are listed when the platform has them registered and ready; when the list cannot be confirmed, STATUS says "unverified". ``` ## Usage ```text anona-compute template list [flags] ``` **Aliases:** `list`, `ls` ## Flags | Flag | Type | Description | | - | - | - | | `--all` | | also list the built-in templates | | `--help`, `-h` | | help for list | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute template logs Source: https://compute.anonalabs.com/docs/cli/reference/template-logs Print a build's log (the newest build unless --build), following it while it runs ```text Print a build's log (the newest build unless --build), following it while it runs ``` ## Usage ```text anona-compute template logs NAME|TEMPLATE_ID [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--build` | string | build ID (default: the newest) | | `--help`, `-h` | | help for logs | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute timeout Source: https://compute.anonalabs.com/docs/cli/reference/timeout Set how long a sandbox lives from now > [!NOTE] > > `extend` is an alias of `timeout`. It replaces the deadline rather than adding to it, and `never` removes it. See [Extend a sandbox](/docs/concepts/lifecycle#extend-a-sandbox). ```text Set the sandbox timeout (POST /sandboxes/{id}/timeout). The sandbox ends DURATION from now; each call replaces the previous value. DURATION is a positive number of seconds or a duration (600, 10m, 2h), or "never" for no time limit at all (the API's timeout -1, also accepted as "-- -1"). "never" is refused when your team has a maximum sandbox lifetime. ``` ## Usage ```text anona-compute timeout SANDBOX_ID DURATION [flags] ``` **Aliases:** `timeout`, `extend` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for timeout | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute usage Source: https://compute.anonalabs.com/docs/cli/reference/usage Show usage and cost for a billing period ```text Show the organization's usage and cost for a billing period (GET /v1/usage on the gateway): meters, totals with the part not yet rated, a projection for the current month, and the most expensive sandboxes. --top N lists the N most expensive sandboxes, reading as many pages of up to 1000 as it takes; --sandbox ID shows one sandbox's row instead. With --json, --top N puts that many rows in the document's sandboxes (without --top it holds the gateway's default page of 50), and next_cursor is set when more remain. Browser logins of any role may read usage; API keys need the usage:read scope. --billing prints the plan, rates and invoices instead (GET /v1/billing): owners and admins, or keys with billing:read. --json prints the gateway's whole document, with snake_case keys. ``` ## Usage ```text anona-compute usage [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--billing` | | show plan, rates and invoices instead (owners, admins, keys with billing:read) | | `--help`, `-h` | | help for usage | | `--period` | string | billing period: current or YYYY-MM (default "current") | | `--sandbox` | string | show this sandbox's usage row instead of the most expensive ones | | `--top` | int | list this many of the most expensive sandboxes, across pages (0 = none) (default 5) | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute vault Source: https://compute.anonalabs.com/docs/cli/reference/vault Store credentials the sandbox never sees ```text Manage the organization's credential vault. A secret stored here is injected into the sandbox's outbound requests by the egress proxy, on the host, after the sandbox has handed the request over. The sandbox cannot read it, and neither can this CLI: no response on any vault route carries a value, so there is no "get" command. A secret records the hosts it may be sent to. That list is not a convenience -- without it, anyone who can write an egress rule could aim your credential at a server they control and read it out of their own access log. A secret with no list cannot be used at all. To use a secret, name it in a sandbox's network rules: anona-compute vault create gh_token --host api.github.com --value-file token.txt anona-compute create --no-internet \ --allow-out api.github.com \ --vault-inject api.github.com:Authorization=bearer:gh_token A rule injects into requests to its host; it does not open that host. With --no-internet, name the host in --allow-out too, or the request is refused. Creating a new binding needs an owner or admin login, or an API key with the vault:bind scope. That scope is in no preset, including full_access: it has to be chosen deliberately when the key is made. ``` ## Usage ```text anona-compute vault [flags] anona-compute vault [command] ``` ## Commands | Command | Description | | - | - | | [`vault allowed-hosts`](/docs/cli/reference/vault-allowed-hosts) | Replace the hosts a secret may be sent to | | [`vault create`](/docs/cli/reference/vault-create) | Store a new secret | | [`vault delete`](/docs/cli/reference/vault-delete) | Delete a secret and every binding of it | | [`vault list`](/docs/cli/reference/vault-list) | List secrets, their allowed hosts and their bindings | | [`vault rotate`](/docs/cli/reference/vault-rotate) | Store a new version of a secret and make it current | | [`vault unbind`](/docs/cli/reference/vault-unbind) | Revoke one binding, leaving the secret | ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for vault | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute vault allowed-hosts Source: https://compute.anonalabs.com/docs/cli/reference/vault-allowed-hosts Replace the hosts a secret may be sent to ```text Replace the hosts a secret may be injected to (PUT /v1/vault/secrets/{name}/allowed-hosts). The list is replaced, not added to. Narrowing it takes effect in seconds: the host agents poll for narrowed authorization and drop the cached value, rather than waiting out its TTL. A secret stored before allowed hosts existed has none recorded, and nothing may use it until this command sets a list. ``` ## Usage ```text anona-compute vault allowed-hosts [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for allowed-hosts | | `--host` | stringArray | a host this secret may be sent to (repeatable; required) | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute vault create Source: https://compute.anonalabs.com/docs/cli/reference/vault-create Store a new secret ```text Store a new secret (POST /v1/vault/secrets). The value is read from --value-file, or from stdin when that is not a terminal. It is never taken from a flag: a flag value is in your shell history and in the process table, where any other user of the machine can read it with ps. A single trailing newline is stripped, so a value written with a text editor or printed by another command does not carry one into the Authorization header. --host is required and repeatable. An entry is an exact name (api.github.com), a subdomain wildcard (*.github.com, which does not cover the apex), or * on its own for any host, which has to be chosen deliberately. A name that already exists is a 409: use "vault rotate" to add a version. ``` ## Usage ```text anona-compute vault create [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for create | | `--host` | stringArray | a host this secret may be sent to (repeatable; required) | | `--value-file` | string | file holding the value ("-" or omitted reads stdin) | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute vault delete Source: https://compute.anonalabs.com/docs/cli/reference/vault-delete Delete a secret and every binding of it ```text Delete a secret (DELETE /v1/vault/secrets/{name}). Every binding of it stops resolving. A sandbox whose policy still names it does not silently lose the header: the egress proxy refuses those requests rather than forward them without the credential. ``` ## Usage ```text anona-compute vault delete [flags] ``` **Aliases:** `delete`, `rm` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for delete | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute vault list Source: https://compute.anonalabs.com/docs/cli/reference/vault-list List secrets, their allowed hosts and their bindings ```text List the organization's secrets (GET /v1/vault/secrets). Values are never listed, because the API never returns one. A secret with no allowed hosts is shown as such: it predates the allowed-hosts list and nothing may use it until "vault allowed-hosts" sets one. A binding made for one sandbox is revoked when that sandbox ends (deleted, timed out or failed), so it is not listed after that. A paused sandbox keeps its bindings. Team and template bindings stay until revoked. ``` ## Usage ```text anona-compute vault list [flags] ``` **Aliases:** `list`, `ls` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for list | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute vault rotate Source: https://compute.anonalabs.com/docs/cli/reference/vault-rotate Store a new version of a secret and make it current ```text Store a new version of a secret and make it current (POST /v1/vault/secrets/{name}/versions). Existing bindings keep working and start resolving to the new value; nothing has to be recreated. Without --host the recorded allowed-hosts list is kept. The output shows the allowed hosts and bindings the secret has after the rotation. The value is read from --value-file or stdin, as with "vault create". ``` ## Usage ```text anona-compute vault rotate [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for rotate | | `--host` | stringArray | replace the allowed hosts as well (repeatable) | | `--value-file` | string | file holding the new value ("-" or omitted reads stdin) | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute vault unbind Source: https://compute.anonalabs.com/docs/cli/reference/vault-unbind Revoke one binding, leaving the secret ```text Revoke one binding (DELETE /v1/vault/bindings/{id}). The secret stays; only this one injection stops. "vault list" prints the IDs. ``` ## Usage ```text anona-compute vault unbind [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for unbind | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute version Source: https://compute.anonalabs.com/docs/cli/reference/version Print the CLI version ```text Print the CLI version ``` ## Usage ```text anona-compute version [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for version | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute view Source: https://compute.anonalabs.com/docs/cli/reference/view Open a live view of a sandbox ```text Mint a live-view token and print the embed URL (the token is in the URL fragment, which browsers never send to a server). Modes: dom (browser agents), terminal (a new shell; needs --control) and desktop. ``` ## Usage ```text anona-compute view SANDBOX_ID [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--control` | | allow input (control scope) | | `--force` | | mint a desktop or dom view even if the sandbox's template has no desktop | | `--help`, `-h` | | help for view | | `--mode` | string | dom, terminal or desktop (default "dom") | | `--ttl` | duration | token lifetime, 30s to 10m (default 10m0s) | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # anona-compute whoami Source: https://compute.anonalabs.com/docs/cli/reference/whoami Show who the CLI is signed in as ```text Show the account behind the current credentials. For a browser login this asks the dashboard (user, organization, role); for an API key it checks the key against the gateway. ``` ## Usage ```text anona-compute whoami [flags] ``` ## Flags | Flag | Type | Description | | - | - | - | | `--help`, `-h` | | help for whoami | Global flags (`--api-key`, `--api-url`, `--json`, `--output`, `--profile`, `--request-timeout`, `--verbose`) work on every command; see [anona-compute](/docs/cli/reference/anona-compute). # Lifecycle and long-running sandboxes Source: https://compute.anonalabs.com/docs/concepts/lifecycle Timeouts, no-limit sandboxes, pause and resume. ```mermaid stateDiagram-v2 [*] --> running: create running --> paused: pause, idle, or timeout with on_timeout=pause paused --> running: connect / resume running --> [*]: delete, or timeout (default) paused --> [*]: delete ``` ## Timeouts Every sandbox has a timeout: the number of seconds from now until its timeout action runs. The action is **delete** by default, or **pause** if you ask for it. Each call to `set_timeout` replaces the previous value, counted from that moment. | Where | Default | | - | - | | SDK `Sandbox.create()` | 300 s | | CLI `create`, `run` | `--timeout 300s` | | API `POST /v2/sandboxes` | 300 s | ```python timeouts.py from anona_compute import Sandbox sbx = Sandbox.create("base", timeout=600) # 10 minutes sbx.set_timeout(3600) # now one hour from this call print(sbx.get_info().end_at) sbx.kill() ``` ```typescript timeouts.ts import { Sandbox } from "@anona-labs/compute-sdk"; const sbx = await Sandbox.create("base", { timeoutMs: 600_000 }); // 10 minutes await sbx.setTimeout(3_600_000); // one hour from now console.log((await sbx.getInfo()).endAt); await sbx.kill(); ``` ```bash timeouts.sh SANDBOX_ID=$(anona-compute create -t base --timeout 10m --json | jq -r .sandbox_id) anona-compute timeout "$SANDBOX_ID" 1h anona-compute delete "$SANDBOX_ID" ``` ## No time limit A timeout of `-1` means **no deadline**: the sandbox runs until you pause or delete it. It reports `endAt` as `9999-12-31T23:59:59Z`, because the E2B schema requires a date. The MCP tools report it as an absent `end_at` instead (the key is omitted, not sent as `null` or empty), and `anona-compute info` shows `never (no time limit)`. A sandbox without a deadline that you pause and resume keeps having no deadline. ```python no_limit.py from anona_compute import Sandbox sbx = Sandbox.create("base", timeout=-1) print(sbx.get_info().end_at) # 9999-12-31 23:59:59+00:00 sbx.kill() ``` ```bash no_limit_api.sh # The REST API takes -1 directly; so do the dashboard and the MCP create_sandbox tool. curl -sS https://api.compute.anonalabs.com/v2/sandboxes \ -H "X-API-Key: $ANONA_API_KEY" -H 'Content-Type: application/json' \ -d '{"templateID": "base", "timeout": -1}' | jq -r .sandboxID > sandbox.id curl -sS -X DELETE "https://api.compute.anonalabs.com/sandboxes/$(cat sandbox.id)" -H "X-API-Key: $ANONA_API_KEY" ``` No plan has a maximum lifetime. If Anona has set one on your team, `-1` and any longer timeout are refused with `400`, naming the limit. With the `anona-compute` CLI, `timeout ID never` sets no deadline; otherwise it takes a positive duration. To change the deadline of a sandbox that is already running, see [Extend a sandbox](#extend-a-sandbox). > [!WARNING] > > The timeout action (delete, or pause with `autoPause`) runs within about a minute of `endAt`, not at the exact second, and running time is billed up to `endAt`, not up to when the action finished. Do not rely on a sandbox still answering after its deadline. > > A sandbox without a deadline is billed for as long as it runs. Let it [pause when idle](#pause-when-idle): paused sandboxes cost only snapshot storage. ## Extend a sandbox Extending a sandbox means giving a running sandbox a new deadline. **Through the API, SDKs, CLI and MCP, the call replaces the deadline; it does not add to it.** `extend 1h` ends the sandbox one hour from the moment you call it, whatever time it had left, so it can also shorten the lifetime. The same call sets no deadline at all. **The dashboard's Extend adds to the time left.** On a sandbox with 25 minutes left, **Extend → 10 minutes** makes it end in 35. A sandbox with no deadline has nothing to add to, so there the choice sets a deadline that long from now. Your plan's maximum lifetime applies to the total: an extension that would end the sandbox further out than the maximum allows is refused and says how much would fit, and the sandbox keeps its deadline. | Where | How | | - | - | | Python SDK | `sbx.set_timeout(seconds)` | | TypeScript SDK | `sbx.setTimeout(ms)` | | CLI | `anona-compute timeout ID DURATION`, or its alias `anona-compute extend ID DURATION` | | REST API | `POST /sandboxes/{sandboxID}/timeout` with `{"timeout": seconds}`; answers `204` | | Dashboard | **Extend** on the sandbox's page (adds to the time left) | | MCP | the `extend_sandbox` tool, with `timeout_seconds` | ```python extend.py from anona_compute import Sandbox sbx = Sandbox.connect("SANDBOX_ID") sbx.set_timeout(3600) # ends one hour from now, not one hour after the old deadline sbx.set_timeout(-1) # no deadline ``` ```typescript extend.ts import { Sandbox } from "@anona-labs/compute-sdk"; const sbx = await Sandbox.connect("SANDBOX_ID"); await sbx.setTimeout(3_600_000); // ends one hour from now await sbx.setTimeout(-1); // no deadline ``` ```bash extend.sh anona-compute extend "$SANDBOX_ID" 1h # also: 600, 10m, 2h anona-compute extend "$SANDBOX_ID" never # no deadline; "-- -1" works too ``` ```bash extend_api.sh curl -sS -X POST "https://api.compute.anonalabs.com/sandboxes/$SANDBOX_ID/timeout" \ -H "X-API-Key: $ANONA_API_KEY" -H 'Content-Type: application/json' \ -d '{"timeout": 3600}' ``` The CLI takes a number of seconds or a duration such as `10m` or `2h`; the SDKs take seconds (Python) or milliseconds (TypeScript); the API and the MCP tool take seconds. The dashboard offers a list from 5 minutes to 30 days, plus **No limit**. No plan limits how far ahead the deadline can be. If Anona has set a maximum lifetime on your team, a longer deadline, or `-1`, is refused with `400` naming the limit. The dashboard's **No limit (pauses when idle)** sets no deadline and an [idle pause](#pause-when-idle) together. ## Pause and resume Pausing snapshots the sandbox's memory and disk and stops the VM. Resuming restores it: running processes, open files and `/dev/shm` carry on where they were. Paused sandboxes are kept until you delete them, except on Free, which deletes one 14 days after it was paused (we email you three days before). They count against your plan's paused-sandbox limit: at the limit a pause you ask for is refused with `403`, and an idle pause or a pause on timeout deletes the sandbox instead, with end reason `paused_limit`. Their snapshot storage is billed per GB-month. See [limits](/docs/concepts/limits). ```python pause_resume.py from anona_compute import Sandbox sbx = Sandbox.create("base") sbx.commands.run("echo kept > /dev/shm/marker") sbx.pause() sbx = Sandbox.connect(sbx.sandbox_id) # resumes a paused sandbox print(sbx.commands.run("cat /dev/shm/marker").stdout) sbx.kill() ``` ```typescript pause_resume.ts import { Sandbox } from "@anona-labs/compute-sdk"; const sbx = await Sandbox.create("base"); await sbx.commands.run("echo kept > /dev/shm/marker"); await sbx.pause(); const again = await Sandbox.connect(sbx.sandboxId); // resumes a paused sandbox console.log((await again.commands.run("cat /dev/shm/marker")).stdout); await again.kill(); ``` ```bash pause_resume.sh SANDBOX_ID=$(anona-compute create -t base --json | jq -r .sandbox_id) anona-compute pause "$SANDBOX_ID" anona-compute list --state paused anona-compute resume "$SANDBOX_ID" anona-compute delete "$SANDBOX_ID" ``` ## Pause on timeout Ask for pause instead of delete when the timeout runs out. The sandbox then waits, paused, until you resume it: ```python pause_on_timeout.py from anona_compute import Sandbox sbx = Sandbox.create("base", timeout=3600, lifecycle={"on_timeout": "pause"}) print(sbx.get_info().state) sbx.kill() ``` ```typescript pause_on_timeout.ts import { Sandbox } from "@anona-labs/compute-sdk"; const sbx = await Sandbox.create("base", { timeoutMs: 3_600_000, lifecycle: { onTimeout: "pause" } }); console.log((await sbx.getInfo()).state); await sbx.kill(); ``` ```bash pause_on_timeout.sh SANDBOX_ID=$(anona-compute create -t base --timeout 1h --auto-pause --json | jq -r .sandbox_id) anona-compute info "$SANDBOX_ID" anona-compute delete "$SANDBOX_ID" ``` `auto_resume` (resume when a request reaches the sandbox's URL) is accepted with pause-on-timeout, but waking on traffic is **Coming soon**: a request to a paused sandbox's URL gets `409` today. Resume with `connect`. ## Pause when idle A sandbox can pause itself once nothing has used it for a while. This is not the same as **Pause on timeout** above: there is no deadline at all. The sandbox runs for as long as it is used, and pauses once it is not. **What counts as use**, restarting the clock: * a request to any of the sandbox's ports, for as long as it is open, so a long process stream, a WebSocket or an SSE response keeps it awake. The one exception is `envd`'s `GET /health`, which SDKs and monitors poll and which says nothing about use; * an open terminal, live view, SSH session or byte pipe; * any process started through `envd` that is still running — a background `commands.run`, a PTY shell, a dev server. **What does not count**, which is the part that surprises people: CPU the guest burns on work it started by itself, outbound traffic the sandbox makes, and API calls *about* the sandbox such as `get` or `list`. A sandbox running a loop that nobody is watching **will** pause. Processes the template starts for itself, such as `sshd` or a desktop's VNC server, are not seen either — but their clients are, through the first two rules. ```python idle_pause.py from anona_compute import Sandbox sbx = Sandbox.create("base", timeout=-1) # no deadline ... sbx.idle_pause.set(15) # ... but pause after 15 idle minutes print(sbx.idle_pause.get()) # 15 sbx.idle_pause.off() # back to running until something stops it sbx.kill() ``` ```typescript idle_pause.ts import { Sandbox } from "@anona-labs/compute-sdk"; const sbx = await Sandbox.create("base", { timeoutMs: -1 }); // no deadline ... await sbx.idlePause.set(15); // ... but pause after 15 idle minutes console.log(await sbx.idlePause.get()); // 15 await sbx.idlePause.off(); await sbx.kill(); ``` ```bash idle_pause_cli.sh # At create time, or on a sandbox that is already running. SANDBOX_ID=$(anona-compute create -t base --timeout never --idle-pause 15m --json | jq -r .sandbox_id) anona-compute idle-pause "$SANDBOX_ID" 1h anona-compute idle-pause "$SANDBOX_ID" off anona-compute resume "$SANDBOX_ID" # a paused sandbox comes back with its memory and files ``` ```bash idle_pause_api.sh # Or at create time, over the API: autoPause takes {"idleMinutes": n} (0 = off; {} = the team default, else 15). curl -sS https://api.compute.anonalabs.com/v2/sandboxes -H "X-API-Key: $ANONA_API_KEY" -H 'Content-Type: application/json' \ -d '{"templateID": "base", "timeout": -1, "autoPause": {"idleMinutes": 30}}' | jq -r .sandboxID > sandbox.id curl -sS "https://api.compute.anonalabs.com/v1/sandboxes/$(cat sandbox.id)/access" -H "X-API-Key: $ANONA_API_KEY" | jq .idlePauseMinutes curl -sS -X DELETE "https://api.compute.anonalabs.com/sandboxes/$(cat sandbox.id)" -H "X-API-Key: $ANONA_API_KEY" ``` `idleMinutes` ranges from 1 to 10080 (one week); `0` turns it off, and `{}` takes your team's default, else 15. The object form also turns on pause at the timeout (it includes `autoPause: true`), so a sandbox that has a deadline as well is paused, not deleted, when the deadline comes; the same goes for `anona-compute create --idle-pause` with a duration. Resume a paused sandbox with `Sandbox.connect(id)`, `anona-compute resume`, or the dashboard. In the dashboard, pick the lifetime **No limit (pauses when idle)** when creating a sandbox and an idle time appears beside it; on a running sandbox the same times are under **Extend**. A paused sandbox costs no compute — only snapshot storage — so idle pausing is the cheapest way to keep a sandbox you will come back to. The SDK's `lifecycle={"on_timeout": "pause"}` (`autoPause: true` on the wire) is the other feature: it pauses at the **timeout**, and idles only if your organization has a default idle time. A sandbox can have both. ## Delete Delete a sandbox with `anona-compute delete`, the dashboard, or `kill()` in the SDK: the SDK keeps the E2B method name, so code written for E2B works unchanged. It returns as soon as the gateway has the request (it waits up to 2 s for the engine) and finishes in the background with retries. The sandbox disappears from `list` at once. ## Fork Fork copies a running sandbox - memory, files and running processes - into new sandboxes. Each copy starts from the exact state the original was in, which is the point: get an agent to an interesting state once, then try ten things from there. The original is **briefly frozen** while its memory is written (about 0.1 s, longer right after it has touched a lot of memory), then keeps running on its own node with the same ID and the same deadline. The snapshot is taken once however many copies you ask for. ```python fork.py from anona_compute import Sandbox sbx = Sandbox.create("base", timeout=300) sbx.files.write("/root/state.txt", "reached an interesting state") sbx.commands.run("nohup sh -c 'while true; do date >> /root/ticks; sleep 1; done' >/dev/null 2>&1 &") # Each entry is a Sandbox or the exception that stopped that one fork. forks = sbx.fork(count=3, timeout=300) for f in forks: if isinstance(f, Exception): print("fork failed:", f) continue print(f.sandbox_id, f.files.read("/root/state.txt")) # the parent's file print(f.commands.run("wc -l < /root/ticks").stdout) # the parent's process, still ticking f.kill() sbx.kill() ``` ```typescript fork.ts import { Sandbox } from "@anona-labs/compute-sdk"; const sbx = await Sandbox.create("base", { timeoutMs: 300_000 }); await sbx.files.write("/root/state.txt", "reached an interesting state"); const forks = await sbx.fork({ count: 3, timeoutMs: 300_000 }); for (const f of forks) { if (f instanceof Error) { console.log("fork failed:", f.message); continue; } console.log(f.sandboxId, await f.files.read("/root/state.txt")); await f.kill(); } await sbx.kill(); ``` ```bash fork.sh SANDBOX_ID=$(anona-compute create -t base --json | jq -r .sandbox_id) anona-compute exec "$SANDBOX_ID" -- sh -c 'echo "reached an interesting state" > /root/state.txt' anona-compute fork "$SANDBOX_ID" --count 3 --timeout 5m # one sandbox ID per line anona-compute delete "$SANDBOX_ID" ``` Each fork is a new sandbox and behaves like one: it takes a slot of your concurrent-sandbox limit, it is **billed like any other sandbox** for as long as it runs, and it inherits the original's template, metadata, timeout policy and network policy, with the lifetime you pass to `fork`. A fork of ten on a plan with room for three is not an all-or-nothing failure. The copies that fit are created, and every other entry of the result says why it was not - `429` when your plan's limit is reached, `503` when the platform is at capacity. The SDK gives you those as exceptions in the same list, in request order. A non-`201` from the API means nothing was forked at all: the sandbox was not running (`409`), or there was no room for even one copy (`429`), in which case the original is not frozen either. > [!NOTE] > > Forking needs the `sandboxes:create` scope, and an API key restricted to particular sandboxes cannot fork. In the dashboard, **Fork** on a running sandbox's page asks how many copies and how long they should live, shows what the batch will cost before you commit, and lists the outcome of each copy. > [!WARNING] > > Each fork request keeps a **checkpoint** of the source sandbox, which the copies read from, and the platform cannot delete one yet - deleting the copies does not free it. So forking is capped per team (32 checkpoints by default); past that, `fork` answers `429` and says so. Ask support to raise it, and tell us what you are building with fork: the cap exists only until checkpoints can be reclaimed. ## Snapshots **Coming soon:** named snapshots you can keep and create from later (`POST /sandboxes/{id}/snapshots`, `GET /snapshots`). Fork takes a snapshot for you and uses it immediately. # Regions and limits Source: https://compute.anonalabs.com/docs/concepts/limits Where sandboxes run, and each plan's limits. ## Region Sandboxes run in a single region today. The API, the dashboard and live view are served from the same region. **Coming soon:** more regions. ## Plan limits | Limit | Free | Starter | Pro | Scale | | - | - | - | - | - | | Sandboxes at once (running only) | 5 | 20 | 100 | 500 | | vCPU at once (running only) | 5 | 40 | 400 | 2,000 | | Largest [sandbox size](/docs/concepts/sizes) | Medium, and at most 2 Medium sandboxes at once | Medium | Large | XL | | Size when you name none | The smallest the template allows (Small for `base`) | The template's own size | The template's own size | The template's own size | | Sandbox creates per minute | 10 | 30 | 60 | 120 | | API requests per minute | 100 | 200 | 300 | 600 | | API keys (active) | 2 | 5 | 20 | 50 | | Custom templates | 2 | 10 | 25 | 100 | | Template storage | 10 GiB | 50 GiB | 150 GiB | 500 GiB | | Largest template image | 10 GiB | 10 GiB | 10 GiB | 10 GiB | | Paused sandboxes | 5, deleted 14 days after pausing (we email you first) | 50 | 200 | 800 | | Public internet egress | Off | On | On | On | | Egress included a month | 5 GB | 25 GB | 100 GB | 250 GB | | vCPU-hours included a month (each with 2 GiB of memory per vCPU) | 100 | 330 | 1,800 | 7,500 | | Vault secrets | Unlimited | Unlimited | Unlimited | Unlimited | Prices are on [Pricing](/docs/pricing). * **At once means running.** Sandboxes that are being created or are running count towards "sandboxes at once" and "vCPU at once"; paused sandboxes never do. * **A sandbox created without a size** runs, on Free, at the smallest size its template allows: Small (1 vCPU, 2 GiB) for `base`, `python`, `node`, `code-interpreter` and templates you built at Small or less, so five run at once; Medium for `desktop` and `agent-desktop`, which count towards the two Medium. On paid plans it runs at the template's own size and counts at that size. See [Sandbox sizes](/docs/concepts/sizes). * **The largest size applies to every create.** A size above it is refused, and so is a sandbox created without a size from a template registered above it. A sandbox you already have keeps its size if your plan changes. * **API requests** counts requests made with an API key. The dashboard's own requests do not count. * **Template storage** is the sum of the image size of each template's current build. The build before it is kept so a rebuild can be rolled back, but it is not counted. One template image is at most the largest template image size. See [Templates](/docs/concepts/templates#build-your-own). * **Paused sandboxes on Free** are deleted 14 days after they were paused. We email the team's owners and admins three days before. Resuming the sandbox starts the 14 days again the next time it is paused. * **Included vCPU-hours and egress** are per calendar month (UTC) and reset on the first. Each included vCPU-hour includes 2 GiB-hours of memory. Free stops when either runs out: new sandboxes and resumes are refused, and running sandboxes are paused (or deleted, end reason `included_usage`, when your paused sandboxes are already at the limit) until the month ends. Paid plans keep running and are billed for what is over. A credit balance you already have pays for what is over first, on any plan; Free stops only once it is spent. Owners and admins are emailed at 80% and 100% of each. Usage is counted hourly, so a team can run past the line by up to about an hour before it applies. See [Pricing](/docs/pricing). * **Public internet egress** is on by default on paid plans. On Free it is off for now (see the table): the 5 GB a month needs a cap that acts in real time, and usage is counted hourly. **Coming soon:** Free egress on, capped at 5 GB. * **Vault secrets** have no limit on any plan. ## When you reach a limit Nothing you already have is stopped or deleted because you reached a limit, or because you moved to a plan with lower limits. New sandboxes, resumes, pauses, API keys and templates are refused until you are back under it. The one exception is Free's included usage for the month: when it runs out, running sandboxes are paused too. Every refusal names the limit and your plan. A refusal at a plan limit has `error_code` `plan_limit_exceeded` and four more fields: ```json { "code": 429, "message": "concurrent sandbox limit reached (5): the Free plan runs at most 5 sandboxes at once - pause or delete one, or upgrade the plan", "error_code": "plan_limit_exceeded", "limit_name": "concurrent_sandboxes", "limit": 5, "current": 5, "plan": "free", "requestId": "3f2c9a0e7b1d4c55a8e6f0b2d4c6e8a1" } ``` | Situation | Response | | - | - | | Sandboxes at once, vCPU at once, or the number of sandboxes at the largest size, on a create, a fork or a resume | `429` `plan_limit_exceeded`, `limit_name` `concurrent_sandboxes`, `concurrent_vcpu` or `concurrent_at_max_size`. Pause or delete a sandbox, then retry | | A size above your plan's largest | `403` `plan_limit_exceeded`, `limit_name` `max_size`; `limit` and `current` are vCPU | | Pausing a sandbox yourself at the paused limit | `403` `plan_limit_exceeded`, `limit_name` `paused_sandboxes` | | Idle pause, or a pause on timeout, at the paused limit | The sandbox is deleted instead of paused, and its end reason is `paused_limit` | | An API key beyond the limit | `403` `plan_limit_exceeded`, `limit_name` `api_keys`. Revoke a key to make room | | A new template beyond the template count, or when template storage is full | `403` `plan_limit_exceeded`, `limit_name` `templates` or `template_storage` (`limit` and `current` in bytes). Rebuilding a template you have is not a new template | | A build whose image would take template storage past the limit, or an image larger than the largest template image | The build fails with a message giving the sizes | | Requests or creates per minute | `429` `rate_limited` with `Retry-After`, `limit_name` `api_requests_per_minute` or `creates_per_minute`, `limit` and `plan` | | A Free paused sandbox 14 days after pausing | Deleted, end reason `paused_retention` | | Free, once the month's included vCPU-hours or egress are used up (and any credit is spent) | Creates, forks and resumes: `403` `plan_limit_exceeded`, `limit_name` `included_vcpu_hours` or `included_egress_gb`. Running sandboxes are paused | ## Other limits These apply as well and are not part of the plan table: | Limit | Free | Starter | Pro | Scale | | - | - | - | - | - | | Longest timeout | No maximum | No maximum | No maximum | No maximum | | Template builds in progress at once | 2 | 2 | 2 | 2 | Every plan allows `timeout=-1`, which means no deadline; see [Lifecycle](/docs/concepts/lifecycle#no-time-limit). Free running time still counts against the month's included vCPU-hours. Across every plan, a team is also limited to about 50 requests a second (bursts of 200) and 120 creates a minute; above that the answer is `429` `rate_limited` with `Retry-After`. Builds in progress count queued builds too: the shared builder runs one build at a time today, so a second build waits in the queue (its log says so) until the first finishes. # Networking and egress Source: https://compute.anonalabs.com/docs/concepts/networking What a sandbox can reach, and who can reach it. ## Egress Every create compiles a network policy from three layers, strictest first: 1. **The platform floor**, which no setting can open: private and internal ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `100.64.0.0/10`, loopback, link-local including the cloud metadata address `169.254.169.254`, multicast and reserved ranges, and their IPv6 equivalents), names such as `localhost`, `*.local` and `*.internal`, and the mail and DNS-over-TLS ports 25, 465, 587, 2525 and 853. Those ports are blocked for TCP and UDP to every destination, and the packets are dropped rather than refused, so a connection attempt to one of them times out. 2. **Your plan's limits.** Paid plans allow the public internet by default; the free plan allows no public egress for now. **Coming soon:** Free egress on, capped at its included 5 GB a month (see [limits](/docs/concepts/limits)). 3. **The sandbox's own policy**: the E2B fields below on create, else your team's egress settings (see [Which policy applies](#which-policy-applies)). | Field | Meaning | | - | - | | `allow_internet_access` | `false` cuts all public egress for this sandbox | | `network.deny_out` | Block these IPv4 addresses or CIDRs. `0.0.0.0/0` blocks all public egress, the same as `allow_internet_access=false` | | `network.allow_out` | Allow these destinations (IPs, CIDRs or host names) even when the rest is blocked. Allow entries win over deny entries | | `network.allow_public_traffic` | Whether the sandbox's ports are reachable without a token (see [Ingress](#ingress)) | ```python egress.py from anona_compute import Sandbox offline = Sandbox.create("base", allow_internet_access=False) offline.kill() only_pypi = Sandbox.create( "base", network={"deny_out": ["0.0.0.0/0"], "allow_out": ["pypi.org", "files.pythonhosted.org"]}, ) only_pypi.kill() no_example = Sandbox.create("base", network={"deny_out": ["93.184.215.14/32"]}) no_example.kill() ``` ```typescript egress.ts import { Sandbox } from "@anona-labs/compute-sdk"; const offline = await Sandbox.create("base", { allowInternetAccess: false }); await offline.kill(); const onlyPypi = await Sandbox.create("base", { network: { denyOut: ["0.0.0.0/0"], allowOut: ["pypi.org", "files.pythonhosted.org"] }, }); await onlyPypi.kill(); ``` ```bash egress.sh anona-compute run --no-internet -t base -- 'echo this sandbox has no internet' ``` Rules the gateway enforces when it compiles your policy: * A destination inside the platform floor is refused with `400`, and so is a host name that resolves into it (this blocks DNS-rebinding tricks). * Host names in `allow_out` need public egress off (`deny_out: ["0.0.0.0/0"]` or `allow_internet_access=false`), as on E2B. Wildcard names and names that do not resolve are refused for now. * `deny_out` takes IPv4 addresses and CIDRs only. * Unknown keys inside `network` are refused, so a typo cannot silently drop part of a policy. * Per plan: up to 512 allow entries and 1,024 deny entries on paid plans (64 and 256 on the free plan), and at most 10 DNS servers. * On the free plan, which has no public egress, `allow_out` opens particular hosts, not the internet: an IP range there can be at most a `/24`, and the addresses and ranges together can cover at most 1,024 addresses. Host names are not limited by this. A policy over either limit is refused with `400`. ## Which policy applies A new sandbox gets the first of these that exists, then the platform floor and your plan's limits on top: 1. The `network` and `allow_internet_access` fields of its create request. 2. Its template's policy (built-in templates have none). 3. Your organization's **team egress settings**: set them on the dashboard's **Network** page (owners and admins), or with `PUT /v1/network`. 4. Your plan's default. Ask the API which policy a sandbox runs with, and where it came from: ```bash effective_policy.sh curl -sS "https://api.compute.anonalabs.com/v1/sandboxes/$SANDBOX_ID/network/effective" \ -H "X-API-Key: $ANONA_API_KEY" | jq '{source, tier, internet: .policy.allow_internet_access}' curl -sS https://api.compute.anonalabs.com/v1/network -H "X-API-Key: $ANONA_API_KEY" | jq '{tier, revision, limits}' ``` ## Change a running sandbox `update_network` replaces a running sandbox's policy. It goes through the same floor and limits as a create. An update that does not mention `allow_internet_access` keeps the sandbox's current setting. ```python update_network.py from anona_compute import Sandbox with Sandbox.create("base") as sbx: # lock it down to one API after setup sbx.update_network({"deny_out": ["0.0.0.0/0"], "allow_out": ["1.1.1.1"]}) ``` ```typescript update_network.ts import { Sandbox } from "@anona-labs/compute-sdk"; const sbx = await Sandbox.create("base"); await sbx.updateNetwork({ denyOut: ["0.0.0.0/0"], allowOut: ["1.1.1.1"] }); await sbx.kill(); ``` The caller needs to be able to control the sandbox: an API key with `sandboxes:use` (and the sandbox on its list, if it has one), or a dashboard member or above. ## Credentials without exposing them The **credential vault** keeps API tokens out of sandboxes. Store a secret, with the hosts it may be sent to, on the dashboard's **Credential vault** page (owners and admins) or with `anona-compute vault create`. Then name it in a header rule for one host; creating a sandbox with a new rule takes the permission in [Bindings and who can make them](#bindings-and-who-can-make-them). The egress proxy adds the header to the sandbox's HTTPS requests to that host; the sandbox, its environment and its disk never contain the value. ```python vault_rule.py from anona_compute import Sandbox # "github_token" was stored in the dashboard's Credential vault first. sbx = Sandbox.create( "base", network={ "deny_out": ["0.0.0.0/0"], "allow_out": ["api.github.com"], "rules": {"api.github.com": [{"transform": {"headers": {"Authorization": "Bearer ${vault.github_token}"}}}]}, }, ) print(sbx.commands.run("env | grep -ci token || true").stdout.strip(), "token variables in the sandbox") sbx.kill() ``` ```typescript vault_rule.ts import { Sandbox } from "@anona-labs/compute-sdk"; const sbx = await Sandbox.create("base", { network: { denyOut: ["0.0.0.0/0"], allowOut: ["api.github.com"], rules: { "api.github.com": [{ transform: { headers: { Authorization: "Bearer ${vault.github_token}" } } }] }, }, }); await sbx.kill(); ``` * A header value must be exactly one `${vault.}`, optionally after `Bearer ` or `Basic `. A literal value is refused with `400`, so no credential ends up in a policy. So is a rule with an empty `headers` object. * Each rule names one exact host. A wildcard such as `*.example.com` is refused with `400`. * Proxies cache a value for up to 60 seconds, so a rotation or revocation reaches running sandboxes within a minute. * The same rules work in the team egress settings, so every new sandbox gets them. * Secret names start with a lowercase letter, then lowercase letters, digits and `_`, up to 63 characters in all; values up to 8 KiB. From the CLI, the same thing without writing the rule by hand: ```bash vault_cli.sh # The value comes from a file or a pipe, never an argument: an argument is in # your shell history and in the process table. anona-compute vault create github_token --host api.github.com --value-file token.txt anona-compute create --no-internet \ --allow-out api.github.com \ --vault-inject api.github.com:Authorization=bearer:github_token anona-compute vault list # names, allowed hosts and bindings; never a value anona-compute vault rotate github_token --value-file new-token.txt ``` There is no `vault get`: no response from the API carries a value, so the CLI has nothing to print. The vault is included in every plan at no charge. ### Allowed hosts Every secret records the hosts it may be sent to. You set them when you store it (`--host` on the CLI, `allowedHosts` in the API), and replace them with `anona-compute vault allowed-hosts` or `PUT /v1/vault/secrets/{name}/allowed-hosts`. An entry is one of: * an exact host: `api.github.com` covers that host only; * `*.` and a domain: `*.github.com` covers every host under `github.com`, but not `github.com` itself. So `*.httpbin.org` does not cover `httpbin.org`; list both if you need both; * `*` on its own, for any host. The list cannot be empty: storing a secret without one is refused with `400`. A rule that sends the secret to a host outside the list is refused with `403`. Narrowing the list also stops existing bindings to hosts it no longer covers. Without the list, anyone who can write a rule could point your credential at a server they control. ### Bindings and who can make them A rule needs a **binding**: a record that this secret goes to this host in this header. The vault page and `anona-compute vault list` show every binding, and each can be revoked. * A rule in a sandbox's create request, or in a network update, is bound for that sandbox alone. Two sandboxes with the same secret, host and header have two bindings, each listed with scope `sandbox` and its sandbox ID. * A rule in the team egress settings or a template's policy is bound once, when the settings are saved, and every sandbox under them uses that binding. * A sandbox's own bindings are revoked when the sandbox ends (deleted, timed out or failed), so they drop out of the list. A paused sandbox keeps its bindings, because it can resume. Team and template bindings stay until you revoke them or delete the secret. Making a new binding takes permission to aim a secret at a host. An organization owner or admin has it, signed in on the dashboard or with `anona-compute login`. So does an API key with the `vault:bind` scope that is not limited to specific sandboxes, and an unrestricted API key (no scopes and no sandbox list, see [API keys](/docs/guides/ci#create-a-key-for-ci)). No preset has `vault:bind`, not even **Full access**: pick it in a custom key. Anyone else who can create sandboxes can still use the rules in the team egress settings and templates, because those bindings exist already. Any other rule in their create request or network update is refused with `403`, even when another sandbox has the same rule: a sandbox's binding is not shared. ### How it works For a host with a vault rule, the egress proxy ends the sandbox's TLS connection and opens its own to the host, which it verifies. So the sandbox sees a certificate for that host issued by the egress proxy's certificate authority, valid for about 7 days. That certificate authority is in the sandbox's system bundle, `/etc/ssl/certs/ca-certificates.crt`, and `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE` and `NODE_EXTRA_CA_CERTS` (also `PIP_CERT` and `GIT_SSL_CAINFO`) point at that file. curl, Python's default SSL context and Node accept the certificate. A client with its own certificate store fails the handshake with a certificate error: Python with certifi's bundle passed explicitly, a Java keystore, or a pinned certificate. Point it at `/etc/ssl/certs/ca-certificates.crt`, or call the host from a client that uses the system bundle. Each rule shows `"audit": "metadata"` in the sandbox's compiled policy. For every request it matches, the egress proxy records the time, method, host, path, response status and size, the rule, and the names of the headers it added. It does not record request or response bodies. ## Ingress All traffic to a sandbox goes through the Anona gateway at `https://-.sbx.compute.anonalabs.com`: | Port | Who gets in | | - | - | | 49983 (`envd`: commands, files) | Only requests with the sandbox's access token, which the SDK holds; signed file URLs for `GET`/`POST /files` | | Any other port | Anyone, when the sandbox allows public traffic or the port is public; otherwise a valid preview link (or its cookie), or the `e2b-traffic-access-token` header | Single ports can also be made public, or shared with signed, expiring links; see [Preview links](/docs/guides/preview-links). Sandbox URLs live on their own domain, so content served from a sandbox never shares cookies with the API or the dashboard. ## DNS Sandboxes resolve names through public resolvers (1.1.1.1 and 1.0.0.1), so they cannot resolve names inside Anona's network. Both are always allowed, whatever the policy. A policy's `dnsServers` does not change them: another address listed there is only allowed as a destination, when `allow_out` has a host name and public egress is off. The free plan accepts only these two. # Sandboxes Source: https://compute.anonalabs.com/docs/concepts/sandboxes What a sandbox is, how to find it again, and what runs inside. A sandbox is a KVM microVM started from a [template](/docs/concepts/templates). It has its own Linux kernel, a writable root filesystem, and its own network policy. Inside it, E2B's `envd` daemon serves commands, files and terminals on port 49983; the SDKs and the CLI talk to it through the Anona gateway. | Property | Value | | - | - | | ID | An opaque string such as `i3k2…`; use it to connect, delete or view the sandbox | | OS | Ubuntu 24.04 | | User | `user` (uid 1000), home `/home/user`, passwordless `sudo` | | Size | Small, Medium, Large or XL (`size` at create; see [Sandbox sizes](/docs/concepts/sizes)), each with its vCPU, memory and disk. Without a size, the template's own (for example 2 vCPU and 1 GiB for `base`) | | State | `running` or `paused`; a deleted sandbox is gone | | Lifetime | A timeout from now, or no deadline; see [Lifecycle](/docs/concepts/lifecycle) | ## Metadata and listing Attach string metadata at create time, then filter on it when you list: ```python metadata.py from anona_compute import Sandbox from e2b import SandboxQuery sbx = Sandbox.create("base", metadata={"job": "nightly-eval", "owner": "ci"}) for info in Sandbox.list(query=SandboxQuery(metadata={"job": "nightly-eval"})).next_items(): print(info.sandbox_id, info.template_id, info.metadata) info = sbx.get_info() print(info.state, info.started_at, info.end_at) sbx.kill() ``` ```typescript metadata.ts import { Sandbox } from "@anona-labs/compute-sdk"; const sbx = await Sandbox.create("base", { metadata: { job: "nightly-eval", owner: "ci" } }); const page = await Sandbox.list({ query: { metadata: { job: "nightly-eval" } } }).nextItems(); for (const info of page) console.log(info.sandboxId, info.templateId, info.metadata); const info = await sbx.getInfo(); console.log(info.state, info.startedAt, info.endAt); await sbx.kill(); ``` ```bash metadata.sh SANDBOX_ID=$(anona-compute create -t base --metadata job=nightly-eval --json | jq -r .sandbox_id) anona-compute list --metadata job=nightly-eval anona-compute info "$SANDBOX_ID" anona-compute delete "$SANDBOX_ID" ``` Metadata keys starting with `anona.` are reserved and refused, and so are the keys the sandbox engine uses itself, such as `host-mount` and anything starting with `cube.` or `io.kubernetes.`, in any letter case. The `400` names the key. ### Names A sandbox can carry a human name: the `name` metadata key. Set it with `metadata={"name": "nightly-eval"}`, `anona-compute create --name nightly-eval` or the **Name** field of **New sandbox**; the dashboard and `anona-compute list` show it beside the ID, and `anona-compute list --name nightly-eval` (or the metadata filter) finds it. Change it later with `anona-compute rename` or `PUT /v1/sandboxes/{id}/name`, which take 1 to 64 letters, digits, spaces, dots, dashes or underscores. The sandbox ID stays the identifier: every API call and command still takes the ID. ## Connect from anywhere A sandbox outlives the process that created it. Any process holding an API key of the same organization can reconnect by ID: ```python connect.py import os from anona_compute import Sandbox sbx = Sandbox.connect(os.environ["SANDBOX_ID"]) print(sbx.commands.run("hostname").stdout) ``` ```typescript connect.ts import { Sandbox } from "@anona-labs/compute-sdk"; const sbx = await Sandbox.connect(process.env.SANDBOX_ID!); console.log((await sbx.commands.run("hostname")).stdout); ``` Another organization's sandbox answers "not found", exactly like a sandbox that does not exist. # Security and isolation Source: https://compute.anonalabs.com/docs/concepts/security How sandboxes are kept apart from each other and from Anona. | Layer | What it does | | - | - | | **A microVM per sandbox** | Each sandbox is a KVM virtual machine with its own guest kernel. Escaping it takes a hypervisor escape, not a container escape. | | **Network policy per sandbox** | An eBPF filter (layer 3) and an egress proxy (layer 7) enforce the [egress policy](/docs/concepts/networking). Private ranges and cloud metadata are always blocked. | | **A gateway in front of everything** | The sandbox runtime's own API is never exposed. Every byte to or from a sandbox passes the gateway, which checks a per-sandbox token. | | **Per-sandbox tokens** | The `envd` access token and the traffic token are derived per sandbox; a token from another organization, or from a deleted sandbox that had the same ID, never matches. | | **Tenant isolation** | A sandbox of another organization answers "not found", the same as one that does not exist, so IDs cannot be probed. | | **Scoped API keys** | Keys carry scopes (read, use, create, delete, usage, billing, integrations, and `vault:bind` for credential vault bindings, which no preset includes) and can be limited to a list of sandbox IDs. See [API keys in CI](/docs/guides/ci). | | **Revocable sessions** | Dashboard and CLI sessions can be revoked on the dashboard; the API stops accepting them within seconds. | | **Short-lived access** | Live-view tokens last at most 10 minutes and can all be revoked at once; SSH certificates last 10 minutes and name one sandbox. | ## Inside the sandbox * Commands run as `user` (uid 1000), with passwordless `sudo` inside the VM. Root inside the VM is not root on the host. * Templates start no daemons at boot beyond `envd` and the Anona in-sandbox agent (which carries live view and SSH). The SSH server starts on first use and listens on loopback only. * Sandboxes have public DNS resolvers and no route to Anona's internal network. ## Credentials Secrets passed as environment variables (`envs=`, or per command) live in the sandbox's memory and disk like any other data, and a pause snapshots them too. For API tokens, use the **credential vault** instead: the egress proxy adds the token to requests to one host and the sandbox never sees it. See [Networking](/docs/concepts/networking#credentials-without-exposing-them). To add the header, the egress proxy decrypts the sandbox's HTTPS traffic to a host with a vault rule: it presents a certificate from the egress proxy's certificate authority, which sandboxes trust, and opens its own verified connection to the host. See [How it works](/docs/concepts/networking#how-it-works). # Sandbox sizes Source: https://compute.anonalabs.com/docs/concepts/sizes Small, Medium, Large and XL: the vCPU, memory and disk a sandbox gets, and which templates run on each. A sandbox's size decides how much CPU, memory and disk it gets. The template decides what is inside it. You pick both when you create a sandbox: any template, at any size that template can run on. ## The four sizes | Size | vCPU | Memory | Disk | | - | - | - | - | | **Small** | 1 | 2 GiB | 10 GB | | **Medium** | 2 | 4 GiB | 20 GB | | **Large** | 4 | 8 GiB | 40 GB | | **XL** | 8 | 16 GiB | 80 GB | Each plan includes the sizes up to its largest: Free and Starter up to Medium (Free runs at most two Medium sandboxes at once), Pro up to Large, Scale up to XL. See [limits](/docs/concepts/limits); prices are on the [pricing page](/docs/pricing). ## Choosing a size ```bash cli.sh anona-compute create -t desktop --size large anona-compute run -t python --size small -- 'python -c "import os; print(os.cpu_count())"' anona-compute template info desktop # the sizes a template can run at, and its minimum ``` ```python size.py from anona_compute import Sandbox sbx = Sandbox.create("desktop", size="large") print(sbx.get_info()) sbx.kill() ``` ```typescript size.ts import { Sandbox, withSize } from "@anona-labs/compute-sdk"; const sbx = await Sandbox.create("desktop", withSize("large")); await sbx.kill(); ``` ```bash api.sh curl -X POST https://api.compute.anonalabs.com/v2/sandboxes \ -H "X-API-Key: $ANONA_API_KEY" -H "Content-Type: application/json" \ -d '{"templateID": "desktop", "size": "large", "timeout": 600}' ``` * The API's create body takes `size`: `small`, `medium`, `large` or `xl`. The stock E2B SDK cannot send that field, so it can set the size as metadata instead: `metadata={"anona.size": "large"}`. That key is read as the size and is not stored with the sandbox's metadata. The Anona SDKs above do this for you. * A sandbox's info (`GET /sandboxes/{id}`, `anona-compute info`) reports the `size` it was created at, with its `cpuCount`, `memoryMB` and `diskSizeMB`. * **Without a size**, a sandbox runs at its template's own size, exactly as before sizes existed. The console's **New sandbox** dialog preselects the template's default size from the table below. * **The first sandbox at a new size takes longer.** The first time anyone creates a template at a size it was not built at, that size is prepared, which takes about half a minute. A create that waits too long for it gets `503` `sandbox_size_preparing` with `Retry-After`, and the CLI and the console retry it for you. Every sandbox after that starts as fast as any other. ## Disk is your working space The disk figure is space for your work: files you create, packages you install, build output, `/home/user` and `/tmp`. The template's own files do not use any of it. A sandbox's root filesystem is two layers. The template image is a read-only layer underneath, shared by every sandbox started from that template. Your disk is a writable layer on top of it. So a 2 GB template on Medium still gives you the full 20 GB to write into, and `df -h /` inside the sandbox shows the disk size with almost nothing used, even though every tool in the template is there. * Changing a file that came with the template copies it into your layer, so that change does count. * When the disk is full, writes fail with `No space left on device`. The template's files are never affected. * A small part of the disk goes to filesystem overhead, a few percent. ## Which templates run on which size Each template has a **minimum size**, and a sandbox can use that size or any larger one. For a template you build, the minimum is the smallest size that meets its vCPU, memory and disk (see [Your own templates](#your-own-templates)). For a built-in template, the minimum is set per template, as in the table below. It does not come from the template's own size, which is what a sandbox gets without a size: `base` runs at 2 vCPU when no size is given, yet it can be created at Small, with 1 vCPU. | Template | Small | Medium | Large | XL | Console default | Without a size | | - | - | - | - | - | - | - | | `base` | ✓ | ✓ | ✓ | ✓ | Small | 2 vCPU, 1 GiB, 1 GiB disk | | `python` | ✓ | ✓ | ✓ | ✓ | Small | 2 vCPU, 2 GiB, 2 GiB disk | | `node` | ✓ | ✓ | ✓ | ✓ | Small | 2 vCPU, 2 GiB, 2 GiB disk | | `code-interpreter` | ✓ | ✓ | ✓ | ✓ | Small | 2 vCPU, 2 GiB, 2 GiB disk | | `desktop` | | ✓ | ✓ | ✓ | Medium | 2 vCPU, 4 GiB, 4 GiB disk | | `agent-desktop` | | ✓ | ✓ | ✓ | Large | 2 vCPU, 6 GiB, 8 GiB disk | `anona-compute template info