git:20260814.5cad4be to git:20261021.e79bb53

# Riffpad

> Watch, approve, and steer AI coding agents from your phone.

## Landing

Watch, approve, and steer AI coding agents from your phone.

Project site: https://riffpad.ai/

## Quickstart

# Quickstart

>

> ```

## 1. Install the CLI

On your computer:

::: code-group

```bash [macOS / Linux]

curl -fsSL https://riffpad.ai/install.sh | sh

```

```powershell [Windows]

irm https://riffpad.ai/install.ps1 | iex

```

:::

The Windows script downloads the latest binary, adds it to your user PATH, and registers a logon autostart task for the daemon; remove it with `riffpad setup --remove`.

Verify:

```bash

riffpad version

```

## 2. Sign in

```bash

riffpad login

```

This opens a browser for GitHub authorization (password login stays available via `--username`). The daemon restarts automatically after login.

Check your account:

```bash

riffpad auth

```

## 3. Pair your phone

```bash

riffpad pair

```

The terminal prints a 6-character code and a QR code. Open <https://app.riffpad.ai> on your phone, sign in with the same GitHub account, then scan or enter the code.

## 4. Start and watch a session

```bash

riffpad run codex

```

Or with a specific agent and prompt:

```bash

riffpad run claude --prompt "Refactor the auth middleware"

```

Sessions appear in the app's Sessions page; open one to watch progress, approve actions, and send instructions.

## Common commands

| Command | Purpose |

|---|---|

| `riffpad login` / `logout` | GitHub device sign-in / sign-out |

| `riffpad auth` | Show the current account |

| `riffpad pair` | Print pairing code + QR |

| `riffpad run <claude\|codex\|kimi>` | Create and run a session |

| `riffpad sessions` | List sessions |

| `riffpad update` | Self-update the binary |

| `riffpad kill` | Kill switch: stop sessions + revoke devices |

---

## Remote control

# Remote control

After pairing, open <https://app.riffpad.ai> (or the local daemon page on port 8787):

- **Sessions**: see every running session with its status light (WAITING FOR INPUT / RUNNING / DONE) and recent activity; tap a card to open it.

- **Session detail**: live chat stream plus tool-call logs; an `Interrupt` button appears while the agent is running; scrolling up loads older history in pages.

- **Approvals**: approve or reject permission requests with one tap.

- **Instructions**: type a message and send it with the `→` button; it travels end-to-end encrypted to your daemon.

- **Devices**: list paired devices, identify this device, revoke access.

## Do I need tmux?

No. `riffpad run` hosts the session for you; `riffpad attach` can also capture a Claude session you started yourself.

If you want a session to survive closing the terminal, pair it with tmux:

```bash

tmux new -s work

riffpad run codex

# Ctrl-b d to detach; reattach later with: tmux attach -t work

```

---

## CLI

# CLI reference

| Command | Description |

|---|---|

| `riffpad login [--url wss://…]` | GitHub device sign-in (default); `--username` for password login |

| `riffpad logout` | Sign out and revoke the relay token |

| `riffpad auth` | Show the current account (live validation) |

| `riffpad pair` | Print a 6-char pairing code and QR |

| `riffpad run [claude\|codex\|kimi] [--name N] [--prompt P] [--cwd D]` | Create a hosted session; the terminal stays visible and interactive |

| `riffpad attach` / `detach` | Inject/remove Claude hooks to capture your own session |

| `riffpad sessions` | List sessions |

| `riffpad status` | Daemon status |

| `riffpad setup [--remove]` | Install/remove the Linux systemd autostart |

| `riffpad kill` | Kill switch: stop all sessions + revoke all devices |

| `riffpad update` | Check and replace with the latest version (SHA256 + atomic swap) |

| `riffpad logs` | Show daemon logs |

| `riffpad version` | Print the version |

## Languages

The CLI output defaults to English. Use `--lang zh` to switch to Chinese; `--lang en` explicitly selects English.

## Environment variables

| Variable | Description |

|---|---|

| `RIFFPAD_RELAY_URL` | Relay address (default `wss://api.riffpad.ai`) |

| `RIFFPAD_RELAY_USER` / `RIFFPAD_RELAY_PASSWORD` | Password login credentials |

| `RIFFPAD_URL` | Local daemon address (default `http://127.0.0.1:8787`) |

| `RIFFPAD_DIR` | Data directory (default `~/.config/riffpad`) |

---

## Architecture

# Architecture

```

┌─────────────────┐ ┌────────────────────┐ ┌──────────────┐

│ Your computer │ │ Cloud relay │ │ Phone/Web │

│ │ WSS │ │ WSS │ │

│ coding CLI │◀────▶│ encrypted envelopes│◀────▶│ session list │

│ (claude/codex) │ │ no decrypt/storage│ │ approvals │

│ ↕ adapters │ └────────────────────┘ │ instructions │

│ daemon │ └──────────────┘

└─────────────────┘

```

- **coding CLI**: Claude Code, Codex, Kimi CLI run on your computer; API keys never leave your machine.

- **daemon**: captures events, injects instructions, and relays approvals through adapters (Claude host protocol / Codex app-server / Kimi ACP).

- **relay**: WebSocket rooms that forward encrypted envelopes; it cannot read content and only stores non-sensitive metadata.

- **client**: the web app (PWA direction), read-only by default; approvals and instructions are explicit actions.

## Session history

Session messages are encrypted and persisted locally by the daemon. The relay never stores message content. On every open, the daemon replays recent history; older messages load on demand as you scroll up.

---

## Security model

# Security model

## End-to-end encryption

- Device keys are exchanged during pairing (X25519 + P-256); the session key is derived on both sides.

- Messages are encrypted with AES-GCM; the relay only sees ciphertext.

- Client keys live in browser storage (native apps will use Keychain/Keystore).

## Zero-knowledge relay

The relay does not persist session content — only necessary metadata (accounts, devices, online state). No plaintext messages are stored.

## Devices & revocation

- One account can pair many devices; each device can be revoked independently.

- `riffpad kill` is a kill switch: stop all sessions and revoke every device.

- Revoking the current device sends the client back to pairing immediately.

## Accounts

- GitHub OAuth is supported today (username/password login remains).

- Login tokens last 30 days and are revoked on sign-out.

---

## FAQ

# FAQ

## Does my computer need to stay on?

Yes. Agents run on your own computer — Riffpad is the remote control. Sessions stop when the computer sleeps.

## Is my data uploaded to the cloud?

Session content is not. Only encrypted envelopes pass through the relay, which never decrypts or stores them; message history stays on your computer.

## Which coding CLIs are supported?

Claude Code, Codex, and Kimi CLI today; DeepSeek / GLM are on the roadmap.

## How many devices can one daemon pair?

Unlimited. Each device is managed and revocable independently.

## What happens on a network drop or daemon restart?

The client reconnects automatically and de-duplicates replay. After a daemon restart, unfinished sessions recover (Codex reattaches its TUI; Kimi/Claude recover read-only).

## How do I report issues?

Open an issue at <https://github.com/riffpad/riffpad/issues> or email hi@riffpad.ai.

---