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

# Architecture

> How CLI, Convex, relay, web, and protocol fit together.

## System components

| Component | Role |
| - | - |
| `apps/cli` | Host shell, local attach, auth, relay bridge, WebRTC transport |
| `packages/backend` | Convex auth, session lifecycle, tickets, onboarding, billing |
| `apps/relay` | Authenticated WebSocket router and WebRTC signaling passthrough |
| `apps/web` | Landing, device-login approval, onboarding, Pro checkout (yearly default), install proxy |
| `packages/protocol` | Shared JSON message schema and codec (`protocolVersion: 1`) |
| `packages/terminal` | Bun-native PTY layer via `wrapper-pty-helper` |
| `packages/logger` | Logging and opt-in telemetry |
| `apps/mobile` | Native iPhone/iPad viewer; TestFlight public beta |

## High-level flow

```mermaid theme={null}
flowchart LR
  hostCli[HostCLI] -->|session open heartbeat close| backend[ConvexBackend]
  viewerCli[ViewerCLI] -->|authorize attach and ticket request| backend
  hostCli -->|ws with host ticket| relay[RelayService]
  viewerCli -->|ws with viewer ticket| relay
  relay -->|input resize| hostCli
  hostCli -->|output session events| relay
  relay -->|broadcast output and close| viewerCli
  hostCli -.->|optional DTLS data channel| viewerCli
```

![Architecture diagram with trust boundaries: your machine runs wrapper shell-host with the PTY and a loopback WebSocket plus registry token for local viewers; Convex handles auth, the share-code gate, session records, and relay tickets; the Fly relay carries signaling and fallback terminal data; remote CLI and iOS viewers connect to the host over an encrypted DTLS P2P data channel by default](https://mintcdn.com/wrapper/JLMnFS4G4wmSxZil/images/wrapper-architecture.webp?fit=max\&auto=format\&n=JLMnFS4G4wmSxZil\&q=85\&s=245854966b7f84dbe51dc086a8ae3e35)

## Session lifecycle

1. `wrapper share` or `wrapper run` starts `wrapper shell-host` (`wrapper install` is optional).
2. Host creates a PTY, binds loopback WebSocket + token, and registers locally.
3. Unshared hosts send nothing to Convex.
4. Local viewers attach with the registry token. No Convex row is required.
5. Share opens a Convex session, issues a hashed share code plus host relay ticket, and starts heartbeats.
6. Viewers request viewer tickets, connect to the relay, and optionally open P2P.
7. Unshare or host exit revokes tickets, closes the Convex row, and closes remote viewers.

The backend expires stale sessions that miss heartbeats.

## Relay auth and routing

Backend-issued relay tickets are short-lived and single-use. Each session has
one host and can have multiple viewers. The relay routes terminal frames and
WebRTC signaling only within that session. Host disconnect closes every viewer.
Peer ids are assigned by the relay.

## Protocol

Wire messages are JSON validated with Zod in `@repo/protocol`. Common types:

* `session.opened` / `session.closed`
* `input` / `output` / `resize`
* `attach` / `detach`
* `error`
* `signal` (WebRTC SDP and ICE)
* `viewer.caps` (whether that viewer may type)

The relay stamps `from` on `input` and drops guest typing unless `canInput` is
true. The host enforces the same rule on P2P input.

Frames have explicit size caps (wire and terminal payload limits) before parse
and fan-out.

## Session access

* A session that is not shared is owner only.
* The owner joins a shared session without a share code.
* A non-owner needs the session id, share code, and a valid ticket.
* Access failures use a uniform denial shape.
* People you invite see output. They cannot type unless the host allows it.

See [Security and privacy](https://docs.wrapper.sh/configuration/security.md),
[Transports](https://docs.wrapper.sh/reference/transports.md), and [Pricing](https://docs.wrapper.sh/reference/pricing.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.