# Quivvo > Quivvo gives each AI agent its own Linux machine in the cloud: a Firecracker microVM with root and a persistent disk, driven from a CLI, a REST API or a hosted MCP server. Machines suspend when idle and bill by the second. ## If you're an AI agent, start here Follow [the setup runbook](https://tryquivvo.com/setup.md). In short: ```bash command -v quivvo >/dev/null || npm i -g quivvo@latest quivvo login --agent --no-wait --json ``` Send your owner `message_for_owner` and end your turn. Don't wait in a loop. Run the same command again later: exit `0` approved, `75` still pending, `76` expired (run it again for a new code), `77` denied. The run that issues the code exits `0` too, so read `status`. Then: ```bash quivvo create --name work --if-not-exists quivvo exec work -- "uname -a" quivvo rm work --yes ``` New accounts wait in a queue for now. Run `quivvo whoami --json`: if `queue.waiting` is true, tell your owner `queue.position` and `queue.invite_url`, and stop. `npx quivvo@latest` works too, but leaves nothing on your PATH, so every later command has to start with it. Don't use `quivvo sh` or `quivvo ssh ` to get started in a tool call: with no terminal they open no shell. ## Long work A command that waits for its result stops at 280 seconds, which is also its default. If it might outlast your own tool's timeout (often 120 seconds), use `--background`: when a tool timeout kills `quivvo exec`, the command is stopped too. A job takes up to 86400 seconds (3600 by default) and goes on if you disconnect: ```bash JOB=$(quivvo exec work --background --timeout 1800 -- "npm test") quivvo jobs wait work "$JOB" --timeout 100 # 124: still running, run it again quivvo jobs logs work "$JOB" --tail 50 ``` For one command on a throwaway machine, deleted afterwards: `quivvo run --push . -- "npm test"`. `run` waits for the whole command, so it's for work shorter than your tool's timeout. For anything longer, `quivvo run --push . --no-wait --timeout 1800 -- "npm test"` starts it as a job and prints the machine and the job. If `run` is killed with no chance to clean up (SIGKILL, say), its machine stays until the server deletes it, at the timeout plus 30 minutes: find it with `quivvo ls` and `quivvo jobs ls `, and delete it with `quivvo rm --yes`. Any other signal deletes it on the way out. ## Other commands ```bash quivvo push ./api work # what git tracks, no .git, no .env quivvo cp work:/data/home/report.txt . quivvo port publish work 3000 # prints an HTTPS URL quivvo snapshot save work --name base # copies /data, nothing else quivvo suspend work # on Free, one machine runs at a time quivvo create --name copy --snapshot base quivvo suspend copy quivvo fork work --name attempt-2 # also copies /data only quivvo suspend attempt-2 quivvo rm copy --yes # on Free, a workspace keeps 3 machines quivvo rm attempt-2 --yes quivvo snapshot rm base --yes # `quivvo rm` leaves snapshots quivvo agent prompt work --env ANTHROPIC_API_KEY -- "fix the failing test" ``` `exec` is for text: under `--json` binary output gets changed, and `warnings` says so. Move binary data with `quivvo cp` and `quivvo push`. Everything else is in [the skill](https://tryquivvo.com/skill.md) and [the CLI reference](https://tryquivvo.com/docs/cli.md). ## Exit codes | Code | Meaning | | --- | --- | | `0` | ok | | `1` | something else went wrong | | `2` | the command line or a request was wrong | | `3` | not signed in, or this key isn't allowed to | | `4` | no such machine, job, snapshot or file | | `5` | a plan limit, or out of credit: the error says who can fix it | | `75` | nothing changed and it may work later: run it again | | `76` | `login`: the code expired | | `77` | `login`: the owner denied it | | `124` | a wait or the command's timeout ran out | | `125` | `exec` or `run` itself failed, so the command's result is unknown | `exec`, `run`, `ssh`, `jobs wait` and `jobs logs -f` exit with the remote code otherwise, so under `--json` look for the `error` key. [Every error code](https://tryquivvo.com/docs/errors.md). ## Facts - API base: https://tryquivvo.com/api/v1. Auth: `Authorization: Bearer qvk_...`. Errors: `{"error":{"code","message","retryable","retry_after_seconds","docs_url","request_id","owner_action"}}`. `GET /whoami` shows what a key may do. - MCP (Streamable HTTP): https://tryquivvo.com/api/mcp. Clients sign in with OAuth at the first tool call, or send the same bearer key. - Network: the CLI needs https://tryquivvo.com and, for `ssh`, `cp`, `push` and `port-forward`, `*.fly.dev`, where machines are reached. - The default machine has 2 vCPUs, 4 GiB and a 10 GiB disk at `/data`, in `ams` (Amsterdam). Home is `/data/home`. - Regions: `ams` (Amsterdam), `iad` (Ashburn, Virginia). Pass `--region` to `quivvo create`, or `region` to the API. A machine that names its region stays there or fails; one that doesn't goes to the default and then to the other region if that one is full. - Suspend keeps memory and processes when it can, and otherwise stops the machine, which keeps only the disk. Keeping memory is documented by the provider up to 2 GB. The API and CLI report which happened in `suspend_outcome` and `resume_outcome`. - Prices: $0.005 per vCPU-hour and $0.011 per GiB-hour while running, $0.20 per GiB-month of disk, and the same for each snapshot, by the size of the disk it copied. The default machine costs $0.054 an hour while running. ## Free plan New accounts get $5 of credit, with no card needed, once per email address. Free runs 1 machine at a time and keeps 3, each up to 2 vCPUs, 4 GiB and 20 GiB of disk, with 3 snapshots. Machines suspend after at most 15 idle minutes. Forking a running machine, starting one from a snapshot or using `quivvo run` while another runs needs a second running slot, so on Free suspend it first. New accounts wait in a queue for now, and the credit arrives with their turn. Each person who signs up with your invite link moves you up 10 places, and a paid plan skips it. ## What's preinstalled | Template | What's on it | | --- | --- | | `universal` (default) | Debian 13 with Claude Code, Codex, Docker, the GitHub CLI, Node.js 22, Bun, Python 3.13, Go, build tools, Chromium with Playwright MCP, and a desktop on demand. | | `minimal` | Debian 13 with git, curl and Python 3.13. The smallest image. | The `universal` template's Chromium is driven through Playwright MCP, headless unless its desktop is running (`quivvo desktop `): see [letting an agent use a browser](https://tryquivvo.com/docs/recipes.md#let-an-agent-use-a-browser). Not preinstalled: anything else, such as Rust, Ruby or Java. You have root, so run `apt-get update` and then `apt-get install`. That's meant to stay through stops and restarts, but only `/data` is guaranteed: snapshots and forks copy nothing else, and a restore can start from a fresh root filesystem, so be ready to install it again. The `minimal` template has no Docker, Node.js, Claude Code or Codex. Claude Code and Codex are installed but not signed in: see [handing over a task](https://tryquivvo.com/docs/recipes.md#hand-a-task-to-claude-code-or-codex). ## For agents - [Setup runbook](https://tryquivvo.com/setup.md): For an agent: install the CLI, sign in without blocking, connect MCP, verify with a real machine, report PASS or FAIL. - [Agent skill](https://tryquivvo.com/skill.md): How to use Quivvo, as a skill to install. `quivvo init` does it for you. - [Quivvo for agents](https://tryquivvo.com/agents.md): Every surface Quivvo has for AI agents: the setup runbook, skill, MCP server, CLI, REST API, SDKs, llms.txt, Markdown pages and discovery files. - [All docs in one file](https://tryquivvo.com/llms-full.txt): Every page below, in one Markdown file. ## Docs - [Quick start](https://tryquivvo.com/docs/quickstart.md): Go from nothing to a shell in your own cloud Linux machine with one command. - [Machines](https://tryquivvo.com/docs/machines.md): How Quivvo machines work: states, suspend and resume, disks, sizes, templates, regions, ports and deletion rules. - [Recipes](https://tryquivvo.com/docs/recipes.md): Copy-paste recipes for Quivvo: a one-shot command, a long background job, a private repo, handing a task to Claude Code or Codex, and letting an agent use a browser. - [CLI reference](https://tryquivvo.com/docs/cli.md): Every command of the quivvo CLI with its flags, exit codes and JSON output: create machines, run commands, copy files, publish ports, open the desktop and take snapshots. - [REST API reference](https://tryquivvo.com/docs/api.md): The Quivvo REST API: authentication, errors, idempotency and every endpoint, with an OpenAPI 3.1 document. - [SDKs](https://tryquivvo.com/docs/sdks.md): The Quivvo SDKs for TypeScript and Python: install, create a machine, run and stream commands, and handle errors. - [MCP server](https://tryquivvo.com/docs/mcp.md): Connect Claude Code, Cursor or Codex to Quivvo's hosted MCP server to create and drive cloud machines. - [Agent sign-up](https://tryquivvo.com/docs/agents.md): How an AI agent with no browser signs itself up for Quivvo without blocking, and gets an API key once its owner approves. - [Errors](https://tryquivvo.com/docs/errors.md): Every Quivvo API error code: what it means, its HTTP status and CLI exit code, whether to retry, and what to do about it. - [Webhooks](https://tryquivvo.com/docs/webhooks.md): Signed HTTP events when Quivvo machines become ready, suspend, stop, fail or are deleted. - [Pricing](https://tryquivvo.com/pricing.md): Quivvo bills running machines by the second. See prices per vCPU-hour and GiB-hour, machine sizes and plans. ## Machine-readable - [OpenAPI document](https://tryquivvo.com/api/v1/openapi.json): The whole REST API, as OpenAPI 3.1. - [Catalog](https://tryquivvo.com/api/v1/catalog): Templates, sizes, regions, plans, prices and exec limits as JSON, no key needed. - [MCP server card](https://tryquivvo.com/api/mcp/server-card): How to connect to the hosted MCP server. - [AI catalog](https://tryquivvo.com/.well-known/ai-catalog.json): What this site offers agents, as an AI catalog. - [API catalog](https://tryquivvo.com/.well-known/api-catalog): Where the API is described (RFC 9727). ## Compare - [AI agent sandbox pricing compared](https://tryquivvo.com/compare/sandbox-pricing.md): What a 2 vCPU, 4 GiB machine costs per hour and per month on InstaBox, boat, Quivvo, Northflank, Fly Sprites, E2B and Daytona, with sources. - [Quivvo vs InstaBox](https://tryquivvo.com/compare/instabox.md): Quivvo and InstaBox compared: price per hour, plans, regions, public URLs, templates, and when to choose each. - [Quivvo vs boat](https://tryquivvo.com/compare/boat.md): Quivvo and boat compared: price per hour, pause versus stop, regions, public URLs, MCP, and when to choose each. - [Quivvo vs E2B](https://tryquivvo.com/compare/e2b.md): Quivvo and E2B compared: price per hour, session limits, disks, and when to choose each. - [Quivvo vs Daytona](https://tryquivvo.com/compare/daytona.md): Quivvo and Daytona compared: price per hour, isolation, disks, SDKs, and when to choose each. - [Quivvo vs Fly Sprites](https://tryquivvo.com/compare/fly-sprites.md): Quivvo and Fly Sprites compared: allocated versus actual-use billing, state, public URLs, and when to choose each. ## Guides - [What is an AI agent sandbox?](https://tryquivvo.com/guides/what-is-an-ai-agent-sandbox.md): An AI agent sandbox is an isolated environment where an agent can run code safely. What the kinds of isolation are, and what to look for. - [How to give Claude Code a cloud machine](https://tryquivvo.com/guides/cloud-machine-for-claude-code.md): Connect Claude Code to a cloud Linux machine using Quivvo's CLI and hosted MCP server. ## Optional - [Quivvo: one computer per AI agent](https://tryquivvo.com/index.md): Linux machines for AI agents: run anything as root, suspend when idle, pay by the second. CLI, API and MCP.