Skip to main content
Every thread runs on a machine: an isolated cloud VM where the agent clones your repositories, runs commands, and edits code. The agent loop runs on Capy’s servers; the machine is where execution happens. Tasks either share their parent thread’s machine or boot their own, with the same lifecycle either way. Only work pushed to git or shipped through a pull request survives the machine. Uncommitted edits, installed packages, scratch files, running processes: all of it is machine state, and machine state is disposable. Anything you want to keep leaves the machine through git.

​
A machine outlives its VM

A machine is the durable identity a thread attaches to. The sandbox actually running behind it, the backing, can die and be rebuilt at any time. “The machine died” almost always means the backing went away: the provider expired it, or it sat idle past the retention window. The next use boots a fresh backing from your project’s dev environment and the thread carries on with the same machine identity. This is why setup investment pays off. Your setup configuration is the recipe every rebuilt backing follows, and a snapshot makes following that recipe nearly instant.

​
How a machine boots

  1. A thread requests a machine. This creates the identity only; no VM yet. Boot overlaps the model’s first turn, so you rarely wait on it.
  2. A backing boots. When your project has a current snapshot, the VM restores from it in roughly 1–2 seconds with dependencies already installed. Without one, a fresh Ubuntu VM boots and pays your full setup time.
  3. Repositories are cloned and checked out. Shallow clones at each repository’s base branch, routed through Capy’s git proxy; no GitHub credentials ever land on the machine.
  4. Environment variables are written and setup scripts run. Variables are written into the machine environment first. A fresh clone runs your initialize then startup scripts; a snapshot restore advances the checkout, runs update_after_checkout only when the commit actually moved, then startup.
  5. The agent works. Tool calls execute on the machine, and the machine stays awake as long as the thread is working.
If a setup script fails, the machine still comes up: the thread gets a workspace warning, the agent sees the failing repository and phase, and it will usually try to repair the workspace by hand. Fix the script in your dev environment so the next machine doesn’t need repairing.

​
Sleep

A machine sleeps when nothing holds it awake. The rules:
  • While the agent works, the machine stays awake automatically.
  • About two minutes after the thread stops working, the machine goes to sleep. Background operations the agent is tracking (a long test run) hold it awake; detached processes (a dev server) do not.
  • The filesystem survives sleep. Memory, processes, and network connections do not. Resume is a cold boot from disk: your checkout and installed packages are intact, but every process is gone.
  • On the next wake, Capy refreshes the checkouts and runs your startup script again, so services configured there come back on their own. Anything started ad hoc stays dead until something restarts it.
  • The machine panel in a thread shows the sleep countdown and offers +5 minutes, a prepaid extension you can stack up to 30 minutes ahead. There is no stop button; an idle machine sleeps on its own within minutes.
A sleeping machine costs nothing. Asleep 14 days, its filesystem moves to colder storage but still resumes. Asleep 30 days, it’s deleted for good. Before you rely on that being fine, apply the rule: anything on that machine you haven’t pushed is gone with it.

​
Watching the machine

The thread pane shows the machine as the agent uses it: terminal output for commands, the growing diff, a file browser, and a live desktop view of the machine’s display, useful when the agent is driving a browser or you asked it to open your app. You never need SSH to see what’s happening.

​
Exposing ports

Ask Capy to expose a port and it serves that TCP port at a public URL: the way to open a dev server the agent started. Two failure modes to know:
  • The URL works only while the machine is awake. Traffic to an exposed URL does not keep the machine awake; use the +5 minutes button or keep the thread working while you click around.
  • Ports 8000, 8080, 8100, and 22222 are reserved for Capy’s own services; run your app on anything else.

​
Moving files between machines

Each task can run on its own machine, and machines don’t share a filesystem. Capy copies files and directories between machines with its transfer_files tool, the only cross-machine path. Within one machine, plain cp does the job. If you need a build artifact from a task’s machine, ask Capy to transfer it; don’t expect it to appear on the primary machine by itself.

​
Sizes and pricing

Machine size is set per project in the dev environment; every new machine in the project uses it, snapshot builds included. You pay by the hour while a machine is awake. Sizes run from Small (1 vCPU, 4 GB) through Big Guy (16 vCPU, 128 GB); the hourly rate for each lives in pricing, the single source for rates. Large is the default and handles most work. Go bigger for heavy builds and large test suites; a size change applies to new machines, not ones already running. What’s installed on every machine (runtimes, Docker, browsers) is covered in VM sandbox.