Machines

Every cloud thread runs on its own Linux VM, where the agent clones your repositories, runs commands, and edits code. A subagent can share its parent's machine or boot its own.

Pushed commits and files in Drive are always safe. The disk survives sleep, but running processes don't. If Capy has to rebuild a machine, unpushed edits, installed packages, and scratch files are lost.

Specs⁠

An organization with purchased balance and no plan can start the same sizes as Lite. To get Big Guy, contact us.

Every size has the same base:

Memory is a hard limit. When memory runs out, the kernel kills processes, so run heavy jobs one at a time or pick a bigger size. You can ask for this in your instructions.

Choose a size⁠

The project's Machine setting chooses the size, or you can ask Capy to change it. New machines and snapshot builds use that size unless a subagent or an automation asks for another. Running machines keep their size.

Large handles most work. Go bigger for heavy builds or several services at once. Size also decides which snapshot disk tier a machine uses.

Sizes above your plan show a lock and the plan that unlocks them. If the project's size is above your plan, for example after a downgrade, new machines can't start until you pick an included size or upgrade.

Pricing⁠

You pay only while a machine is awake, at the hourly rate in the specs table, prorated for the exact time. Each time the machine goes to sleep, you also pay for a 2-minute wind-down. A sleeping machine costs nothing.

Machine time is always paid in Capy credits, even when the model runs on your own subscription or API key. Without a plan or a balance, starting a cloud thread opens a plan dialog.

Plan limits⁠

Your plan sets how much memory your organization's awake cloud machines can use at once.

• Every awake cloud machine counts, including subagents on their own machines and pull request reviews. A review machine uses 4 GB by default.
• Subagents on a shared machine, sleeping machines, and threads on your own computer don't count.
• A thread that a service user starts through an API key can use at most half the limit by default.

When a new machine doesn't fit, Capy waits up to one minute for room, then shows Cloud machine couldn't start with the memory in use. To make room, wait for other threads to finish or archive the ones you're done with, and their machines sleep within minutes.

To raise the limit on Lite or Pro, choose See plans. On Max or Enterprise, contact support with your organization name and the limit you need.

Preinstalled tools⁠

A running machine keeps the image it booted with, so it can have older versions than these. If a version matters, ask Capy to check it.

The shell switches to the Node version in .nvmrc or .node-version on cd, and installs it if needed. The agent installs anything else with sudo. To install something on every machine, put it in your initialize script.

Docker and Compose work inside the VM. Containers stop when the machine sleeps, so start services you always need in your startup entries.

Kernel limits⁠

There is no /dev/kvm, so the accelerated Android emulator, QEMU with KVM, Firecracker, and VirtualBox don't work or fall back to slow software emulation.

You can't load kernel modules, so modprobe and insmod fail. These features are built in:

• Overlay filesystem, FUSE, cgroup v2, and user namespaces
• Bridges, veth pairs, TUN devices, and WireGuard
• iptables and nftables for IPv4 and IPv6, with connection tracking, NAT, and masquerading

These are missing:

• VXLAN, which some container networks such as Flannel use
• IPVS and IP sets, which kube-proxy's IPVS mode and some network plugins use
• The iptables statistic, recent, and physdev matches
• nftables inet, bridge, and netdev tables, and the fib expression

Run Kubernetes locally⁠

Kind, Minikube with the Docker driver, and k3s can run a local cluster. A Service with more than one ready endpoint breaks Service routing for the whole cluster, because kube-proxy needs the missing statistic match. Run every Deployment behind a Service with one replica, CoreDNS included.

• With Minikube, minikube start --driver=docker works as is.
• With Kind, run kubectl -n kube-system scale deploy/coredns --replicas=1 after kind create cluster.
• With k3s, use the host-gw Flannel backend on a bridge with a private address. NetworkPolicy isn't enforced.

Before you install k3s, create the bridge:

sudo ip link add k3s-host type bridge
sudo ip addr add 10.240.0.1/24 dev k3s-host
sudo ip link set k3s-host up

Then put this in /etc/rancher/k3s/config.yaml:

node-ip: 10.240.0.1
flannel-iface: k3s-host
flannel-backend: host-gw

To test with several replicas, point kubectl at a cluster you run elsewhere. Reach a private cluster through Tailscale.

Sleep⁠

A machine sleeps about 2 minutes after the thread stops working, unless one of these holds it awake:

• The agent is waiting on a background command, which holds it awake for up to the command's timeout, at most 6 hours.
• A shell, desktop, or preview tab is open and visible in the thread pane.
• Someone uses a preview URL.
• Someone chose Keep awake 4h.

A process the agent leaves running, such as a dev server, doesn't hold the machine awake.

The disk survives sleep, but memory, processes, and connections don't. On wake, Capy refreshes the checkouts and reruns your startup entries, but a process started by hand stays stopped. Tabs in the machine's Chrome reopen without their page state.

The agent wakes the machine when it needs it. To wake it yourself, choose Wake machine in the thread pane.

A machine that sleeps for 30 days is deleted. If Capy can't resume a machine, the thread gets a fresh one from your dev environment, and unpushed work is lost. To limit the loss, ask the agent to push at milestones. Install dependencies in your setup scripts, and turn on snapshots so a rebuilt machine starts with them.

Long-running jobs⁠

For a long build, test run, or rendering job, ask Capy to run a background command with an explicit timeout and wait for it:

Run python paint.py as a background command.
Set its timeout to six hours and wait for it to finish.
Save completed images as you go.

Background commands default to a 30-minute timeout, with a maximum of 6 hours per command. The timeout counts elapsed time, not CPU time. At the timeout, Capy stops the command. Waiting again does not extend that timeout or restart a stopped job.

A background command alone does not keep the machine awake. The agent must wait on that command. A timer alone or a detached process, such as a dev server, does not keep it awake either.

For jobs longer than 6 hours, ask Capy to split the work into shorter commands and save results between commands. Sleep stops running processes, and waking the machine does not resume them. Keep-awake does not protect a job from a machine failure or replacement. Ask Capy to save important outputs to Drive or push them to git.

You pay the machine's hourly rate while it stays awake, including while the agent waits. If your credits or allowance cannot cover a longer wait, Capy reports a one-hour keep-awake limit instead.

Keep a machine awake⁠

In the app, Keep awake 4h keeps an idle machine running until the displayed end time. Cancel keep awake ends the reservation early. You can choose Keep awake 4h again after the reservation ends.

You pay while the machine is awake, and the reservation can end early if your credits or allowance run out. Keep awake 4h is greyed out while the agent works, so choose it once the turn ends. This reservation does not change a command's timeout.

The public API has no keep-awake reservation endpoint. For API jobs, include the background-command and wait instructions in your message to Capy.

Previews⁠

Ask Capy to expose a port, and it publishes the app as a preview with its own URL that you can also open from Slack. Previews are listed under Exposed apps in the thread's Overview tab.

The in-app browser suggests listening ports when you type a port number. Ports 8090, 8484, 8485, 49983, and 61000 to 61999 are reserved for Capy.

Anyone with the URL can open a preview while the machine is awake, without signing in. Treat the URL like a password. Only your organization's members can wake the machine from it.

Each request to the preview keeps the machine awake 5 more minutes, for up to 4 hours after you or the agent last used the thread. When the machine is asleep, the URL shows a Start the machine link that asks you to sign in and wakes it.

When a preview opens after sleep, Capy reruns the app's start command if nothing is listening. The URL stays the same across sleeps.

To stop a preview, ask the agent, or kill its shell from the + menu.

Network access⁠

Machines can reach the public internet. To reach private services, connect Tailscale. Machines join your tailnet when they boot, and your ACLs decide what they can reach.

To reach Google Cloud, AWS, Azure, HashiCorp Vault, or another OIDC-compatible service without a stored key, set up OIDC federation. Capy signs a short-lived OIDC token for each machine, and your cloud exchanges it for its own credentials. For services that need a long-lived key, store it as a variable, which Capy writes into the machine's environment at boot.

Good to know⁠

• Cloud machines run Linux only. For macOS or the iOS Simulator, run the thread on your Mac with the desktop app.
• There is no SSH. Open a shell or the machine's desktop from the + menu in the thread pane.
• Machines don't share a filesystem. Ask Capy to transfer files from a subagent's machine.
• If a setup script fails, the machine still starts and the agent usually repairs the workspace. Fix the script for the next machine.
• To speed up boots, turn on snapshots and keep startup entries short.
• Apps behind a portless-style hostname router open in previews with that hostname.