Relay

Run AI coding agents on your machine. Control them from any screen.

A private, self-hosted remote cockpit for Claude Code, Codex, OpenCode, and Hermes.

中文 · Install a backend · Security · Handbook

Relay leaves your source code, shell access, and CLI credentials on the computer you control. Its Flutter client connects from phone, Web, or desktop to a small Node.js backend running beside your projects—there is no Relay cloud account and no hosted middleman.

🖥️ Runs where your code lives Your agents and projects stay on your backend machine.

📱 One client, every screen Use the same interface on mobile, Web, and desktop.

🔐 Private by design Import an encrypted, revocable credential for each device.

See Relay in 60 seconds

Keep real coding sessions within reach

Stream replies, cancel a turn, search history, export Markdown, and switch away while work continues. Each workdir + agent context supports up to eight named, resumable conversations.

Chat, coordinate, and manage files from mobile

Persistent chat Follow a long-running agent session from anywhere.	Swarms Let specialized agents work in one shared transcript.	Remote files Browse, upload, download, and change the active work tree.

_{These screenshots were captured in Chromium against an isolated demo backend; they contain no production credentials or project data.}

How it fits together

flowchart LR
    C["Flutter client<br/>Phone · Web · Desktop"]
    R["Relay backend<br/>Node.js on your machine"]
    A["Persistent agent sessions<br/>Claude · Codex · OpenCode · Hermes"]
    F["Projects and files"]
    T["Resumable PTY shell"]

    C -->|"authenticated HTTP + SSE"| R
    R -->|"local CLI protocols"| A
    R -->|"filesystem policy"| F
    C -. "single-use WebSocket ticket" .-> T
    R --> T

Loading

The active workdir belongs to each client and is sent on every request. A conversation is scoped by workdir + agent + session, so unrelated sessions can run concurrently without sharing a global backend directory.

What you can do

	Capability	What it gives you
💬	Live, persistent chat	Streaming replies, cancellation, named sessions, cross-device history, search, and Markdown export.
🐝	Multi-agent Swarms	Shared transcripts, per-member roles and controls, parallel waves, bounded @mention handoffs, and reusable JSON templates.
🎛️	Agent controls	Model, reasoning effort, permission tier, install/auth status, credential-expiry countdown, and Fast mode for Claude/Codex.
📁	Files and terminal	Allowed-path browsing, uploads, downloads, zipped folders, workdir switching, and one resumable PTY per device credential.
📊	Quota workflows	Claude/Codex usage views plus one queued prompt for the next detected five-hour reset.
🔔	Notifications	In-app/browser alerts, with optional Web Push and Android FCM for configured deployments.

Claude Code and Codex are the primary integrations. OpenCode and Hermes are available as experimental, host-managed integrations. All four keep their credentials on the backend host; Relay never logs an agent in for you.

Quick start

1. Prepare the backend machine

Install Node.js 18+ and at least one supported CLI on Linux, macOS, or Windows. Claude and Codex must already be logged in on that host; OpenCode and Hermes use the provider configuration managed there.

Run the setup command for your backend OS from the repository root:

Backend OS	Setup command
Linux	./backends/linux/setup.sh
macOS	./backends/macos/setup.sh
Windows PowerShell	.\backends\windows\setup.ps1

The installer walks through direct access, a named Cloudflare Tunnel, or a temporary Quick Tunnel. Use HTTPS before exposing a direct deployment publicly. Linux also needs PM2 and the native tools listed in the backend requirements; Unix hosts need zip for folder downloads.

2. Import an encrypted device credential

Setup prints an encrypted QR code and writes .relay.png / .relay.json files under server/credentials/. Import one by camera, image/file, or pasted JSON, then enter its passphrase. Camera scanning is mobile-only; every client supports file or pasted-JSON import. Generate a separate revocable credential for each device.

3. Pick a project and start working

Choose the backend, set the workdir, and open an agent conversation or Swarm. For service commands, networking details, and platform notes, continue with the backend guide.

Security boundary

• Every HTTP API route requires a revocable bearer token; failed attempts are rate-limited.
• Credential exports use PBKDF2-HMAC-SHA256 and AES-256-GCM.
• The terminal exchanges that bearer token for a short-lived, single-use WebSocket ticket; the long-lived token never appears in the socket URL.
• The file API denies known Relay, SSH, Claude, and Codex secret paths and can be restricted further with RELAY_FS_ROOTS.
• Quota reporting may read and refresh host OAuth files, but token values never reach the Relay API or client.

Important

Relay is not a sandbox. Agent and terminal processes have the permissions of the backend OS user. Run it as a restricted non-root user, terminate TLS for public deployments, and read SECURITY.md plus the production checklist first.

Development

flutter pub get
flutter analyze --no-pub
flutter test --no-pub
npm --prefix server install
npm --prefix server test

Run the client with flutter run. To serve a self-hosted Web build:

flutter build web --no-pub --pwa-strategy=none --no-web-resources-cdn
npm --prefix server start

The Web flags intentionally disable the service worker and bundle CanvasKit locally. Windows release builds have been exercised; macOS/Linux desktop packaging and secure-storage validation are less mature. See the development handbook.

Relay/
├── lib/          shared Flutter client
├── server/       Node.js backend and tests
├── backends/     OS-specific install/service adapters
├── docs/         operations and architecture handbook
├── scripts/      development, deployment, and screenshot helpers
└── test/         Flutter tests

Contributors and coding agents should read AGENTS.md. Release history is in CHANGELOG.md, and Relay is released under the MIT License.