Architecture

Rye has a local component and a remote control plane. The local component is responsible for supervision and enforcement. The control plane receives presence, policy, and audit data.

Local components

Component	Responsibility
`rye` CLI	User commands for auth, daemon control, proxy setup, diagnostics, wrapping, history, config, and upgrades.
`ryed` daemon	Long-running process that owns proxy lifecycle, IPC, policy sync, local storage, retention, history ingestion, and upload.
Local proxy	MITM proxy that intercepts configured HTTPS domains and evaluates policy before forwarding requests.
API shim	Optional reverse proxy for clients that support a configurable model API base URL.
Wrapper	PTY supervisor that runs an assistant process with proxy environment variables and records local telemetry.
App shims	Shell shims that make commands such as `claude` and `codex` automatically run through Rye.
SQLite store	Local cache for requests, responses, policy snapshots, events, history ingest checkpoints, and retention.

Request flow

rye wrap claude
  -> child process starts with proxy environment variables
  -> model API request goes to 127.0.0.1:18080
  -> Rye extracts request metadata and body
  -> policy store evaluates the request
  -> allowed requests forward upstream
  -> denied requests receive a structured 403 response
  -> request, response, and policy events are stored locally
  -> batches upload to the control plane

The daemon also sends presence heartbeats when gRPC is enabled. This lets the control plane understand which devices are active and which client version they run.

Local IPC

The CLI communicates with ryed over a local IPC socket. Commands such as rye up, rye down, rye status, and rye daemon stop send JSON requests to the daemon. The CLI starts the daemon automatically when needed. You can also manage it directly:

rye daemon start
rye daemon status
rye daemon restart
rye daemon stop
rye daemon logs --lines 100

Policy sync

Rye starts with a local default policy. When connected, the daemon syncs policy snapshots over gRPC. Policy snapshots are:

Validated before use.
Cached in SQLite.
Applied atomically.
Acknowledged back to the server.
Reused locally if the network is unavailable.

Data retention

Rye stores captured data locally before upload. The default retention limits are:

7 days by age.
512 MB by local database size.
Retention checks every hour.

Use exports carefully. Request and response bodies can contain source code, prompts, tool output, and secrets copied into context.

Start here

Core concepts

Configure Rye

Operate

Architecture

Local components

Request flow

Local IPC

Policy sync

Data retention

​Local components

​Request flow

​Local IPC

​Policy sync

​Data retention

Local components

Request flow

Local IPC

Policy sync

Data retention