# Computers

> A computer is a machine of its own for a coding agent. Create one, connect Claude Code to it, work in it over a shell or its desktop, and let it shut down when idle; the home disk stays.

Some work needs a place whose files are still there tomorrow: a checkout, a half-finished migration, the notes of a long task. A computer is that place. It is an app with one machine that runs the computer image, a home disk mounted at `/data` that outlives the machine, and a desktop you can watch or take over from the console.

## Sizes

| Size | vCPU | Memory | Home disk |
| --- | --- | --- | --- |
| `small` | 1 | 2304 MB | 50 GB |
| `base` (default) | 2 | 4096 MB | 100 GB |
| `large` | 4 | 8192 MB | 128 GB |

An organization on starting credit may run 2 computers at a time; see [Limits and quotas](https://docs.rytiv.com/concepts/limits.md).

## 1. Create a computer

**Console**

Open **Computers**, choose **New computer**, give it a name and a size. The console creates the app, the home disk and the key, and deploys the computer image.

**CLI**

```bash
ry computer create dev-1 --image rytiv/computer:0.1.0
ry computer create dev-2 --size large --image rytiv/computer:0.1.0
```

`--image` names the computer image: Rytiv's released image `rytiv/computer:<version>`, or a `build:<id>` of your own. Without `--image`, the CLI reads `RYTIV_COMPUTER_IMAGE` from the environment and refuses when neither is set.

**curl**

A computer is an app created with `computer: true`, a home volume attached to it, a secret `COMPUTER_VIEW_KEY` the desktop needs, and a deploy of the computer image with the size and a sleep rule. The CLI runs these calls in that order:

```bash
curl -X POST "https://api.rytiv.app/v1/apps" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "dev-1", "computer": true}'
```

Then `POST /v1/volumes` (`dev-1-home`), `POST /v1/apps/dev-1/attach` with the volume, `PUT /v1/apps/dev-1/secrets` with `COMPUTER_VIEW_KEY`, and `POST /v1/apps/dev-1/deploy` with `{"image": "rytiv/computer:0.1.0", "memoryMb": 4096, "vcpus": 2, "internalPort": 8080, "suspendPolicy": {"mode": "suspend", "idleSeconds": 600, "stopAfterSeconds": 86400}}`. See the [API reference](https://docs.rytiv.com/reference/api/computers.md).

Names are 2 to 31 characters of lowercase letters, digits and hyphens. The home disk is a volume named `<computer>-home`; it is kept while the computer is shut down and when its machine is replaced.

What the image brings: Node.js with npm, Codex, OpenCode, git, the GitHub CLI, Python 3 with pip, a browser and a desktop. Claude Code is not pre-installed; inside the computer, `rytiv-setup claude` installs it with its own official installer under its own terms (`--stable`, `--version <v>` and `--print` are accepted), and `rytiv-setup` alone shows what the image has and has not.

## 2. Connect Claude Code

Two ways, for two kinds of work.

1. **Claude Code on your laptop, Rytiv as its tool.** Add the MCP server once; the agent then creates computers, runs commands in them and snapshots them with the tools `computer_create`, `computer_exec` and `computer_snapshot`:

   ```bash
   claude mcp add --transport http rytiv https://api.rytiv.app/v1/mcp --header "Authorization: Bearer <your key>"
   ```

   Then ask in plain words: "Create a computer on Rytiv, clone the repository into it and run the tests."

2. **Claude Code inside the computer.** Open a shell in it and install Claude Code there; the session keeps running when your laptop is closed:

   ```bash
   ry ssh dev-1
   ```

   Inside: `rytiv-setup claude`, then `claude`. Sign in with your own Claude account; nothing of it touches Rytiv.

A computer the MCP tool `computer_create` makes is an agent machine: it does not sleep on its own, and it can take [snapshots](#snapshots). A computer from the console or `ry computer create` shuts down when idle and keeps its home; it takes no snapshots.

## 3. Work in it

```bash
ry exec dev-1 -- git status
ry exec dev-1 --dir /data -- npm test
ry ssh dev-1
ry forward dev-1 3000:3000
```

`ry exec` runs one command and exits with its exit code; `ry ssh` opens an interactive shell over the Rytiv API, no SSH keys needed; `ry forward` brings a port of the computer to your machine without a public port. Each of them wakes a shut-down computer. Through MCP, `computer_exec` does what `ry exec` does, as an argument list without a shell.

Files you want to keep go under `/data`, the home. The root disk is the image's and starts fresh at every boot.

## 4. Watch or take over the desktop

```bash
ry computer view dev-1
ry computer control dev-1
ry computer release dev-1
ry computer audit dev-1
```

`view` gives a link to watch, for any number of viewers, valid 60 to 3600 seconds (default 900). `control` gives a link to take keyboard and mouse: there is one holder per machine, the agent inside pauses while you have control, and `--force` takes control from the current holder. `audit` shows who got which link and how control ended. The console shows the same desktop on the computer's page.

## 5. Idle shutdown

After 10 minutes without activity the computer shuts down; your files stay. Every size is above the 2048 MB up to which a machine sleeps with its memory, so a computer stops instead: open programs end, and the next `ry exec`, `ry ssh`, request or console visit boots it fresh with the home disk as it was. CPU load, a held control lease and an open viewer with frames flowing count as activity.

While it is shut down it costs nothing for memory and CPU; the home disk is billed as a volume. See [Credit and prices](https://docs.rytiv.com/billing.md).

## Snapshots

A machine created with `durableCheckpoint: true` (what the MCP tool `computer_create` does, and `POST /v1/apps/:name/machines` with that field) can be snapshotted and restored:

| Method | Path | What it does |
| --- | --- | --- |
| `POST` | `/v1/machines/:id/checkpoints` | `{label, memory, comment}`. Takes a snapshot now. |
| `GET` | `/v1/machines/:id/checkpoints` | The machine's named snapshots |
| `POST` | `/v1/machines/:id/checkpoints/:label/restore` | Brings the machine back to that snapshot. With `keepCurrent: true` (the default) the current state is saved first. |
| `DELETE` | `/v1/machines/:id/checkpoints/:label` | Forgets a snapshot |

Disk only (`memory: false`, the default) is a short pause, and a restore boots fresh with the files as they were. With memory (`memory: true`) a restore resumes the very processes; the pause grows with the machine's memory. Labels use letters, digits, `.`, `-` and `_`, start with a letter or digit, and are at most 63 characters; `auto-` is reserved. Through MCP, `computer_snapshot` takes one. Such a machine also survives a host failure with its last automatic checkpoint.

## Delete

```bash
ry apps destroy dev-1
ry volume destroy vol-1a2b3c4d
```

Deleting the app removes the machine; the home volume stays until you delete it too (`ry volume list` shows it). Both cannot be undone; the CLI asks you to type the name, automation passes `--yes`.