On your machine

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.

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.

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

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

ryph setup

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

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:

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

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 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

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, your local Ryph can send every check to it and have them run there.

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:

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.

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.

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 on your own server, or Kubernetes for a team. Choose a deployment compares them.