# On your machine

> Install the Ryph binary, answer three questions, and give an agent its first task.

- **Best for:** Trying Ryph out
- **Setup:** One command
- **Runs:** Containers on your machine’s Docker
- **Isolation:** Runs on a confined network. One process holds every key.
- **Data:** Embedded Postgres
- **Scale:** Your laptop, while it’s on

The `ryph` binary runs all of Ryph in one process: the web app, the control plane, the model proxy, the MCP gateway, memory, automations and the forge. It carries its own Postgres, so there's no database to install.

What runs where, on your machine:

- **The ryph process**: Every service, plus its own Postgres. Holds Web app, Control plane, Model proxy, MCP gateway, Memory, Automations, Forge, Embedded Postgres.
- **Docker** (locked down by default): With confined internet, an internal network with no route out but through Ryph. Holds Run, Run.

One process holds every service and the database. Runs are containers on your machine’s Docker, and stop when the process does.

This is the way to try Ryph on your own machine. To run it for a team, or to keep agents working while your laptop is closed, use a [long-running deployment](https://ryph.ai/docs/deployment.md).

## What you need

- macOS or Linux, on arm64 or x86_64.
- `git`.
- Docker, to run agents. Docker Desktop works on a Mac. On Linux, Docker Engine 28 or later lets Ryph confine runs to their own network.
- A few GB of free disk for the agent image, which Docker pulls on the first run.

## Install

```sh
curl -fsSL https://ryph.ai/install.sh | sh
```

The script picks the build for your platform from `files.ryph.ai`, checks its signature, and installs `ryph`. Builds are signed and published for macOS and Linux, on arm64 and x86_64.

## Set it up

```sh
ryph setup
```

Setup asks three questions. Pick answers with the arrow keys and Enter.

| Question     | What it decides                                                                                      |
| ------------ | ---------------------------------------------------------------------------------------------------- |
| Master key   | Mint a new key or paste your own. It seals every model provider key and tool credential Ryph stores. |
| Agent runner | Docker, the images agents run in, and how much of the internet a run gets.                           |
| Repositories | Where agents find code: a folder on this machine, GitHub, GitLab, or a Radicle node.                 |

The folder you give is only a boundary. Agents can't see anything in it until you add a repository in the web app.

With `RYPH_MULTIUSER=on`, setup also asks how to send mail, for registration and password-reset links. On your own it isn't needed, so it isn't asked.

For the internet question, choose **confined**. Each run then sits on an internal Docker network with no route out, and reaches the internet only through Ryph's egress proxy and its allowlist.

Setup needs Docker running. Without it, setup stops before the first question, tells you how to fix it, and writes nothing. `ryph up` won't start until an agent runner is set up.

Your answers go in `~/.ryph/config.env`, which you can edit by hand. `ryph config` shows what each setting resolves to and where it came from. Run `ryph setup` again whenever you want to change them.

### Without a terminal

Every question has a flag, so a script or a coding agent can set Ryph up without one. `--yes` takes the default for every question no flag answers:

```sh
ryph setup --yes --egress confined --github cli --repo-root ~/code
```

`ryph setup --help` lists the flags. A choice this machine doesn't offer is refused with the ones it does, and a token given as `-` is read from stdin.

Add `--no-input` to any command to make sure it never asks anything. `ryph up --no-input` skips setup, opens no browser, and doesn't ask what to do with runs when it stops. `ryph login --no-open` prints a sign-in link instead of opening it.

## Start it

```sh
ryph up
```

The web app opens at `http://localhost:3000`. On your own machine Ryph is single-user: there's no registration, and you sign in with a link.

From there:

1. **Add a model key**

   Under **Model keys**, add a key for a model provider. Agents reach the model through Ryph, which keeps the key.

2. **Connect a repository**

   Under **Repos**, connect a folder on this machine, a GitHub repository, a GitLab project or a Radicle node. [Connect your code](#connect-your-code) has the details.

3. **Give an agent a task**

   Create an agent and give it something to do. The first run waits while Docker pulls the agent image.

## Connect your code

| Source                   | How it connects                                                                                                                                                                     |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A folder on this machine | Pick it under Repos → Connect repository → On this machine. Agents work on its commits, and an approved patch lands as a branch in that repository. No git host or token needed.    |
| GitHub                   | Uses your GitHub CLI login (`gh auth login`) or a token. Ryph acts on GitHub as you.                                                                                                |
| GitLab                   | gitlab.com or your own instance, 17.0 or newer. Uses your `glab` login or a personal access token with `api`, `read_repository` and `write_repository`. Ryph acts on GitLab as you. |
| Radicle                  | Connects through a Radicle node.                                                                                                                                                    |

Agents never receive a credential for your git host. They clone through Ryph's forge, and your working copy isn't touched: a run sees your commits, not uncommitted edits.

## Run checks on a deployment

Checks are the commands a repository declares in `.ryph/checks.yml`, which Ryph runs on the work agents produce. If you also have a [long-running deployment](https://ryph.ai/docs/deployment.md), your local Ryph can send every check to it and have them run there.

An agent on your machine commits and asks for checks. Your deployment runs them, sends results back to the agent, and reports statuses to your git host, so the pull request opens with its checks already passed.

The agent iterates against the deployment’s checks before it hands back its work. The deployment reports every result to the git host, so the pull request opens with its checks already green.

That's useful for two reasons:

- **Pull requests open green.** A deployment with checks on reports their results to your git host. When an agent on your machine iterates against those checks, the deployment has already posted passing statuses for its final commit by the time the pull request opens.
- **Heavy checks run elsewhere.** Long test suites, builds and services run on the deployment's machines, which leaves your laptop's CPU, memory and battery for you.

To set it up, add this to `~/.ryph/config.env` and restart `ryph up`:

```sh
RYPH_CHECKS=on
RYPH_CHECKS_REMOTE_URL=https://ryph.example.com
RYPH_CHECKS_REMOTE_TOKEN=ryph_pat_…
```

Mint the token on the deployment under **Account settings** → **API tokens** → **Mint a token**, and tick `checks:request` and `repos:read`. It belongs to you, so you need write access to the repositories on the deployment. The URL must use HTTPS, except for `localhost`, and can't point back at your own instance.

The deployment needs checks turned on and the same repositories connected, matched by their forge address. It reads the checks file, picks the images, services and limits, runs the checks on its own machines and reports them to your git host. Results and logs show up on your runs as usual.

> [!NOTE]
> **If the deployment is down**
>
> Checks retry, then report an error. They stay with the deployment the whole time. Let any local checks finish before you switch.

## Where your data lives

Everything is in `~/.ryph`: the database, the master key and the files runs were given. The master key is stored next to the database, not in it.

`ryph backup <file>` writes a snapshot of the database, and `ryph restore <file>` loads one. Stop Ryph before either. A snapshot doesn't include the master key, so keep a copy of `~/.ryph/secrets.key` somewhere safe as well.

## Stopping

Press Ctrl-C. If runs are still going, Ryph asks whether to keep running, cancel them first, or leave them for a quick restart.

> [!WARNING]
> **Runs need Ryph running**
>
> Everything a run uses lives in the one process. A run that's left behind survives only if Ryph is back within about a minute.

## Going further

Ryph on a laptop is good for trying things out. Once agents should keep working without you, move to a deployment that stays on: [Docker Compose](https://ryph.ai/docs/docker-compose.md) on your own server, or [Kubernetes](https://ryph.ai/docs/kubernetes.md) for a team. [Choose a deployment](https://ryph.ai/docs/deployment.md) compares them.