Machines

What states can a machine be in?

Through the CLI and REST API, commands, files, jobs, connecting and the shell all wake a suspended or stopped machine. That restarts its bill, so the CLI and the answer say so. quivvo logs, quivvo status, quivvo ps and quivvo history don't wake it, and nor does a request to its public URL. The MCP server's read tools don't either.

What does suspend actually do?

Suspend tries to keep memory and running processes. Our provider documents that up to 2 GB of memory, so it may not work on a 4 GiB machine. When it can't be done, the machine is stopped instead: the disk is kept, and memory and processes are lost.

Both count as success, and the API and CLI report which one happened:

• suspend_outcome on the machine is suspended or stopped.
• resume_outcome on the machine is what its last boot came back as: resumed, with memory back, or cold_boot, a fresh boot from the disk. A command that woke the machine has it on its own answer too, with a warning if it was a cold boot.

If your work depends on what's in memory, check those fields rather than assuming. Webhooks follow what really happened: you get machine.stopped for a suspend that became a stop.

When does a machine suspend itself?

A machine with no commands, shells, tunnels or running background jobs for its auto-suspend time suspends itself, with the same fallback to a stop. The default is 30 minutes. Paid plans can turn it off; the Free plan goes up to 15 minutes and uses that by default. A running background job counts as activity, so a server started as a job keeps its machine awake and billing until the job ends. A job is killed at its timeout: 3600 seconds by default, and 86400 at most. So pass --timeout 86400 for a server, and start it again when it ends.

To have a machine deleted whatever happens, create it with --delete-after MIN (delete_after_minutes in the API). auto_delete_at shows when.

What is kept, and for how long?

Everything under /data survives stops, restarts and resizes. Snapshots copy the /data disk, and you can start new machines from them or restore one onto a machine.

Only /data is guaranteed. Packages installed with apt-get live on the root filesystem, which is meant to stay through stops and restarts. Snapshots and forks don't copy it, and a copy doesn't run the original's setup script. Restoring a snapshot, or a move to another host, can give the machine a fresh root filesystem from its template, and a setup script doesn't run again then either. So keep what you can't lose on /data, and be ready to install the rest again. See setting a machine up once.

Command history keeps a machine's newest 100 commands for 30 days, and goes when the machine is deleted. A workspace keeps the newest 8 MiB of history across its machines, so very long output pushes out older commands sooner.

When a machine is deleted, its setup script and ports go at once. A record of it stays for 35 days, so that repeating a delete succeeds and this month's usage can name it, and a workspace keeps the newest 500 of those. A workspace keeps its newest 1 MiB of feedback, for 90 days.

The disk lives on one host, and there are no automatic backups. Keep anything you can't lose somewhere else as well, such as a git remote.

How do snapshots and forks work?

quivvo snapshot save copies the disk. quivvo fork copies a machine's disk into new machines. Copies boot fresh with no running processes, whatever state the source was in. Each fork stands alone, and a partial failure lists the ones that couldn't be made in failed. Copies are made by the provider. If it won't make one, the answer is a provider_error, nothing is created and the source is untouched. A snapshot is charged as disk, $0.20 per GiB-month for the size of the disk it copied, from when it's ready until it's deleted.

A copy can still be reading from what it was copied from after it boots. So a machine can't be deleted while a snapshot or fork of it is being made, and a snapshot can't while a machine is being made from it. That's a conflict with retry_after_seconds: try again later. quivvo rm leaves a machine's snapshots: delete those with quivvo snapshot rm.

A fork counts as a running machine, so on the Free plan, where 1 runs at a time, suspend or stop the source first and make one copy at a time.

What sizes, templates and regions are there?

vCPUs are shared: a machine bursts to full cores, then settles to a baseline if it stays busy for long stretches. Memory and disk are yours alone.

The universal template also has Chromium, with Playwright MCP to let an agent drive it, and a desktop that runs only when you start it: see letting an agent use a browser and watching on a desktop. Anything else, you can install: you're root, so run apt-get update and then apt-get install. The minimal template has no browser or desktop.

Regions: ams (Amsterdam), iad (Ashburn, Virginia). With no --region, a new machine goes to ams, or to the other region if that has no room, and region on the machine says where. Naming a region means that region and no other.

A machine's disk lives on one host. If that host is full when a stopped or suspended machine starts, Quivvo tries to move it to another host in its region, with a copy of /data and the same URL. It comes back as a cold boot, and anything installed outside /data may be gone. If there's no room anywhere in the region, the start fails with capacity and nothing changes.

What are the Free plan's limits?

New workspaces get $5 of credit, with no card needed, once per email address. On Free, 1 machine runs at a time and a workspace keeps 3, each up to 2 vCPUs, 4 GiB and 20 GiB of disk, with 3 snapshots, and creates up to 60 machines an hour. See pricing for the other plans, or run quivvo whoami to see your own limits.

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.

How long can a command run?

A command that waits for its result stops at 280 seconds, which is also its default, and exits 124. A background job takes up to 86400 seconds, 3600 by default, and goes on if you disconnect. See recipes.

If the caller of a waiting command goes away, the command gets SIGTERM, then SIGKILL 3 seconds later. A job isn't affected. An agent's tool timeout (often 120 seconds) is a caller going away, so use --background for anything that might outlast it.

quivvo exec prints output as it's produced, all of it, so what ran before a kill is already on your side. Under --json without --stream, or with --tail-bytes, nothing prints until the end, so get it back with quivvo history and then quivvo output. Under --json and through the API, long output keeps its first 256 KiB and last 768 KiB per stream, with a line saying how many bytes were left out, and --tail-bytes keeps just the end. quivvo output shows the first 16 KiB and last 48 KiB of each stream of a past command, including what a stopped command had printed by then. It can only keep what the command's answer kept, so after --tail-bytes that's just the tail. A job's output is in quivvo jobs logs.

What does exit 137 mean?

It was killed, usually for running out of memory. When the kernel's out-of-memory killer fired while a command ran, oom_killed is true on the result, the job and the history entry. That's machine-wide, so on its own it doesn't prove this command was the victim, but together with 137 it usually does. Use a bigger size: stop the machine, then quivvo resize work --vcpus 2 --mem-mib 4096.

How do public URLs work?

quivvo port publish serves a port on the machine's URL.

• A machine has one URL, and it serves one port: the last one published. replaced_port says which one it stopped serving.
• A machine can have 10 published ports. quivvo port ls lists them all, including ones its URL no longer serves, until you unpublish them, and default marks the one it does. Unpublish that one and the URL serves the highest port left.
• It answers only while the machine runs. A request to it doesn't wake a suspended machine, so resume it first. To keep a server up, start it as a background job with --timeout 86400, which counts as activity but ends at that timeout, or on a paid plan turn auto-suspend off with quivvo auto-suspend dev 0.
• Use quivvo port-forward for a private tunnel to any port. It runs until it's killed, so in a tool call start it in the background. With --json it prints the port at once.

How do I run Claude Code or Codex inside a machine?

The universal template has both installed, not signed in. See handing a task to Claude Code or Codex. Sign-ins are saved in ~/.claude and ~/.codex, on the persistent disk, so they survive stops and restarts. Snapshots include them, so any machine started from a snapshot is signed in as well. Snapshots are private to your workspace.

When are machines and snapshots deleted?

Abandoned machines and snapshots are deleted, always after an email warning and a final reminder 2 days before.

• Credit at zero: everything goes 7 days after the warning, or 30 days if the workspace has ever paid.
• On the welcome credit alone: a machine not used for 14 days goes 7 days after the warning, and so do snapshots once no machine in the workspace has been used for that long.

Adding credit, resuming the machine, or starting a machine from the snapshot cancels it. Disks and snapshots are charged until then, so a balance can dip below zero. Active paid plans are exempt, and the delete_after field on machines and snapshots shows the date.