How Remote Claude Code Works

System Diagram

Three components, one encrypted channel

Your phone and desktop both connect outbound to the relay. The relay routes messages but cannot read them.

beachviber-architecture.md

## BeachViber System Architecture Phone (PWA) Cloud Relay BeachViber Agent ┌──────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ React │ │ Serverless │ │ Node.js Agent │ │ Zustand │ │ REST + WebSocket │ │ Claude Code CLI │ │ Web Crypto │ │ Database │ │ Platform crypto │ │ Tailwind │ │ Auth + Email │ │ Local IPC │ └──────┬───────┘ └────────┬─────────┘ └────────┬─────────┘ │ │ │ │ encrypted msg │ encrypted msg │ │──────────────────► │ ──────────────────► │ │ │ │ │ ┌────────────────┴────────────────┐ │ │ │ RELAY CANNOT READ MESSAGES │ │ │ │ Routes opaque encrypted blobs │ │ │ │ No plaintext ever touches relay │ │ │ └────────────────┬────────────────┘ │ │ │ │ │ Tool Approval Flow │ │ ◄────────────────────────────────────────────── │ request approval │ ──────────────────────────────────────────────► │ approve / deny │ │ │ ┌──────┴───────┐ ┌────────┴─────────┐ ┌───────┴──────────┐ │ Auto-Approve │ │ Auth Layer │ │ Approval Flow │ │ Claude settings│ │ Token auth │ │ Local IPC │ │ allow-list │ │ Email + OAuth │ │ approval timeout │ │ │ │ Input validation │ │ owner-only │ │ Phone-Approve │ │ Device auth │ │ │ │ Everything not│ │ Timing-safe │ │ Hook Lifecycle │ │ in allow-list │ │ comparisons │ │ Auto-managed │ │ │ │ │ │ │ └──────────────┘ └──────────────────┘ └──────────────────┘

Tech Stack

Built with modern, audited tools

📱

Mobile PWA

React, Vite, Tailwind CSS, Zustand, Web Crypto API, Web Speech API

☁

Cloud Relay

Serverless compute, REST + WebSocket APIs, Database, Email, adaptive password hashing, zod

💻

BeachViber Agent

Node.js, Claude Code CLI, platform crypto, local IPC, tool-use hooks

Protocol

Message protocol

A structured message protocol handles everything from pairing to streaming responses.

🔗 Connection & Pairing

Registration, encrypted handshake, and verification messages that establish a secure link between your phone and desktop. Includes multi-desktop management and keep-alive heartbeats.

💬 Session Management

Session lifecycle messages for creating, resuming, and ending coding sessions. Includes project and session history browsing so you can pick up where you left off.

⚡ Coding

Prompt delivery, real-time streaming responses, and the tool approval flow. When Claude needs to run a tool, your phone receives an approval request and sends back a decision.

🛠 System

Heartbeats, error reporting, and status updates that keep the connection healthy and inform both sides of any issues. Designed for resilience across unreliable mobile networks.

Message Flow

How a prompt travels from phone to desktop

Every message between your phone and desktop follows the same encrypted path through the relay. Here's what happens when you send a prompt.

1

You type a prompt on your phone

The PWA encrypts your prompt with AES-256-GCM using the shared key established during pairing. The plaintext never leaves your phone — only the encrypted blob is sent over the network.

2

The relay routes the encrypted blob

The relay receives an opaque payload it cannot decrypt. It reads only the routing metadata in the message envelope to deliver the blob to the correct desktop connection. No prompt content is ever visible to the relay.

3

The BeachViber agent decrypts and starts a session

The BeachViber agent decrypts the prompt with AES-256-GCM and passes it to Claude Code CLI. Claude Code runs in your project directory with access to all your local tools, packages, and environment — exactly as if you were typing at the terminal.

4

Responses stream back through the same encrypted channel

As Claude generates output, the BeachViber agent encrypts each chunk and sends it back through the relay to your phone. Streaming messages arrive token-by-token so you see responses in real time. When Claude needs to run a tool, an approval request is sent to your phone for review.

🔐 How encryption and tool approval work in detail

Design Principles

Why we built it this way

🔌 Outbound-only connections

Both phone and desktop connect outbound to the relay. No port forwarding, no VPN, no firewall rules. This means BeachViber works from any network - home, office, hotel WiFi, or mobile data - without any router configuration.

🛠 Hook-based integration

Instead of wrapping or replacing Claude Code, BeachViber uses Claude Code's official hook system. The agent installs a tool-use hook on start and removes it on exit. This means you always run the real Claude Code binary with its full capabilities, not a fork or proxy.

⚡ Stateless relay

The relay stores no session data, no message history, no code content. It maintains only the minimum state needed for routing: connection IDs and device registrations. If the relay goes down, nothing is lost - reconnect and continue where you left off.

📱 PWA over native app

The phone app is a Progressive Web App rather than a native iOS/Android app. This means instant updates (no app store review), works on any device with a browser, and can be installed to the home screen for a native-like experience. The encryption runs entirely in the browser using the Web Crypto API with non-extractable private keys.