> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rye.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How the Rye CLI, daemon, proxy, wrapper, and control plane work together.

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

```txt theme={null}
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:

```bash theme={null}
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.