# How Rytiv works

> The building blocks your agent works with, how a request becomes a running machine, what sleeps and what stays, and the project model that comes next.

Everything on Rytiv belongs to an **organization** (a team in the console). An API key acts as one organization, and every name it uses is looked up inside that organization only.

## The building blocks

**Apps** are the unit everything else hangs off. An app has a name that is unique across Rytiv and answers on `https://<app>.rytiv.app`. It runs one or more **machines** from an image you deploy, or it is a static site served at the edge without a machine. Secrets, deploys, releases, logs, domains, schedules and jobs belong to an app. See [Apps](https://docs.rytiv.com/apps.md).

**Computers** are apps of a special kind: one machine from the computer image, a home disk at `/data` that outlives the machine, and a desktop you can watch or take over. They are the place an agent works in. See [Computers](https://docs.rytiv.com/computers.md).

**Sandboxes** are machines with a deadline. They start from a template (the image an app of yours runs, or a build), run commands, hold files, and are removed at their deadline. See [Sandboxes](https://docs.rytiv.com/sandboxes.md).

**Postgres** databases run on machines of their own with their data on a volume. Every database can be branched (a copy-on-write copy, ready in seconds) and forked (a full copy from its archive, from any moment in the last 7 days). See [Postgres](https://docs.rytiv.com/postgres.md).

**Volumes** are disks that outlive machines; **buckets** are S3-compatible object storage; **custom domains** put your names on an app. See the [guides](https://docs.rytiv.com/guides/buckets.md).

## Machines

A machine is one virtual machine with its own kernel. It is `requested`, `scheduled`, `starting`, `running`, `suspending`, `suspended`, `stopping`, `stopped`, `deleted` or `failed`. A deploy creates machines for an app one at a time: the new machine must boot and answer on its port (and pass the health check, if set) before an old one is taken out of traffic; if it fails, the old version keeps serving.

A machine that **declares a port** gets no traffic until that port answers. This is a promise, not only behaviour: a migration that runs before the app starts listening never sees traffic against a schema it does not expect.

## What sleeps and what stays

An app sleeps only if you give it a sleep rule (`--sleep 5m`); a new app never sleeps on its own. A machine up to 2048 MB sleeps with its memory and resumes in well under a second on the next request; a larger machine stops instead and boots cold, its disk kept. A computer shuts down after 10 minutes without activity; its home disk stays. A database is suspended after 5 minutes without a query and woken by the next connection, where the region's hosts act on the policy.

What stays through a stop, a replacement or a host failure: a volume, a computer's home, a database's data and archive, a bucket's objects, an agent machine's checkpoints. What does not: a machine's root disk (it is the image's), open programs, and anything on a sandbox at its deadline.

## Three ways in

| Way | For | Where |
| --- | --- | --- |
| MCP server | Your coding agent | `https://api.rytiv.app/v1/mcp`, see the [quickstart](https://docs.rytiv.com/quickstart.md) |
| CLI `ry` | You, in a terminal or in CI | [CLI reference](https://docs.rytiv.com/reference/cli.md) |
| REST API | Your own code | [API reference](https://docs.rytiv.com/reference/api.md) |

All three use the same API and the same keys, and they see the same apps, databases and machines. The console is where you sign in, create keys, watch a computer and top up credit.

## Where it runs

Your apps, databases and files stay in the region of your workspace, in the EU at launch, and a machine never leaves its region. See [Regions](https://docs.rytiv.com/concepts/regions.md) and [Security and data](https://docs.rytiv.com/concepts/security.md). Every bound the platform enforces is on [Limits and quotas](https://docs.rytiv.com/concepts/limits.md); every error code on the [error catalog](https://docs.rytiv.com/concepts/errors.md).

## The project model

Rytiv is becoming the place where your agent builds a whole project: you connect it once and say "build project XY on Rytiv". Each project has three parts with three levels of risk:

- a [sandbox](https://docs.rytiv.com/concepts/sandbox.md) where the agent works freely,
- a [twin](https://docs.rytiv.com/concepts/twins.md) for every task, a disposable copy of production,
- [production](https://docs.rytiv.com/concepts/production.md), which serves your users.

Reversible steps run without asking. Only an irreversible step waits for a [confirmation](https://docs.rytiv.com/concepts/confirmations.md) with your passkey. Projects as an object of the API are not available yet; the pieces (agent tokens with a class, database branches, preview apps, computers, automatic rollback after a deploy) are, and [Projects](https://docs.rytiv.com/concepts/projects.md) says how they fit together today.