Ryph separates coordination from execution. The orchestrator owns durable task and run state. The runner lives inside the agent environment and executes one work item. Model, tool and Git access cross dedicated gateways.
The control plane
The web app is a backend for the browser. The orchestrator manages agents, tasks, runs, access decisions and liveness. It talks to a provisioner to create or stop the environment for a run.
Provisioners implement the same launch contract across Docker and Kubernetes. That common interface does not imply identical isolation. For example, Kubernetes runs are Jobs with a non-root runner and no mounted service-account token. On Docker, only confined runs are held to the egress proxy; the allowlisted and direct modes leave Docker’s default route open.
The runner and harness
The runner prepares the checkout, drives the harness, reports heartbeats and history, and hands back the result. The harness is the integration with the coding agent itself; the current real-agent image uses pi.
The runner creates pi’s configuration in a temporary directory and explicitly loads Ryph’s MCP extension. Repository-supplied pi configuration and extensions are not automatically loaded. Repository context can still reach the agent as task material, and configured setup steps execute inside the environment.
The gateways
| Component | Responsibility |
|---|---|
| Model proxy | Enforce the model scope, substitute the real provider key, stream responses and meter usage |
| MCP gateway | Authenticate the run, filter tool availability and calls, and attach upstream credentials |
| Forge gateway | Serve connected-repo Git reads, accept patch bundles, and deliver to GitHub, GitLab or Radicle |
| Egress proxy | Verify a signed host allowlist and forward permitted internet requests |
The egress proxy does not replace the others. Model and MCP calls use their dedicated gateways and credentials. Package downloads and other permitted internet requests use the forward proxy. Egress and isolation explains the distinction.
Supporting services
The historian stores transcript chunks and events, and streams live updates. Automations own recipes and fire records. Chat connects room messages to active runs. Memory curates proposals into a shared canon and provides briefs and retrieval.
Recording is not a transactional prerequisite for every model or tool request. Usage recording is best effort, and the runner’s history buffer is bounded. A storage outage can leave a gap in history without preventing the agent from making progress.
Local and distributed deployments
The ryph binary includes the web app, embedded Postgres through PGlite, and local platform services. Git, the container runtime and agent images remain separate prerequisites. The binary also runs the forge gateway in-process, on its own port, for cloning and for pull request, merge request and patch delivery to GitHub, GitLab or Radicle.
Compose and Kubernetes deploy services separately. The Helm chart also defines namespace and network boundaries, and runs.runtimeClassName puts runs under a sandboxing runtime such as gVisor when the cluster offers one.
The credential-free, patch-only description applies to every repository, including one on your own machine. A local repository is connected like any other, and its runs clone it through the forge gateway.
Follow the implementation
See the host composition, runner entry point, and Kubernetes network policies.