amplinkdocs

Overview

Secure mobile viewport for local AI coding sessions. One phone, any adapter.

Overview

Amplink turns a phone into a secure viewport for AI coding sessions running on your own machine. The phone renders a small primitive set, the bridge manages adapters locally, and the relay forwards opaque encrypted bytes. API keys and provider credentials stay on the desktop.

What Amplink Does

Amplink gives you one protocol and one mobile UI across multiple local backends:

  • claude-code for persistent Claude Code sessions over stream-json
  • codex for Codex-backed sessions
  • openai for OpenAI-compatible endpoints and local model servers
  • opencode and pi for additional local agent backends
  • Community adapters for anything that can emit Amplink primitives

The phone does not talk directly to Anthropic, OpenAI, or any other model provider. It talks to the local bridge, and the bridge talks to adapters.

Key Concepts

Bridge: The local orchestrator. It creates sessions, routes prompts, buffers events for reconnect, and exposes the JSON-RPC interface used by the phone.

Relay: A room-based WebSocket forwarder. It knows which bridge public key is mapped to which room, but it does not decrypt or inspect application payloads.

Session: One live agent connection. A session might wrap a Claude Code subprocess, a Codex transport, or an OpenAI-compatible endpoint.

Turn: One request/response cycle within a session. Turns stream blocks until they end in completed, failed, or stopped.

Block: The unit the phone renders. Amplink intentionally keeps the primitive surface small: text, reasoning, action, file, and error.

Adapter: The translation layer between a native backend and Amplink primitives. Adapters do not own encryption, relay logic, or phone-specific behavior.

System Shape

Phone
  ├── renders Amplink primitives
  ├── pairs with QR + Noise XX
  └── reconnects with Noise IK
          ↕ encrypted WebSocket
Relay
  ├── forwards opaque bytes
  └── maps bridge public key -> current room
          ↕ encrypted WebSocket
Bridge
  ├── manages sessions and adapters
  ├── exposes JSON-RPC
  ├── buffers events for replay
  └── serves local files and dispatch endpoints

Cloudflare is an optional sidecar for the current desktop listener and voice workflow. It is not the trust anchor for bridge sessions.

Why The Design Is Strict

  • Provider credentials stay on the user's machine.
  • The relay is zero-knowledge by default.
  • iOS is secure-only: there is no plaintext mode on the phone.
  • The reconnect story is protocol-driven, not best-effort UI state.
  • The primitive surface is small enough to keep adapter work and mobile rendering stable.

Next Steps