# Claude Remote — MacLustr Command Center

A private, single-administrator web application that exposes the real Claude Code CLI, running inside tmux on a Mac Studio of the MacLustr cluster, to any browser. Nothing is simulated: the browser terminal is an xterm.js view attached to a tmux session in which claude (or a login shell) runs.

Production instance: https://claude.spboucher.ai → node M5M36 (deployed 2026-11-10).

This README is a summary. Every statement about behaviour is backed by the source; anything that is not implemented or not verified is listed under Limitations and in the "Limitations / not verified" section of each document.

# Architecture

 browser (desktop / phone)
    │  HTTPS + WSS
    ▼
 Caddy on the public gateway (BHS64) ── TLS termination, reverse proxy
    │  WireGuard tunnel (the node dials out; no inbound port on the LAN)
    ▼
 M5M36 ─ apps/server   Fastify, port 8620
    │      auth (password + passkey/TOTP), REST + WebSocket API /api/v1,
    │      static web app (apps/web/out), PostgreSQL 17 (loopback), audit, notifications
    │
    │  unix socket (0600, dir 0700) + bearer token — HTTP and WebSocket
    ▼
         apps/runtime  no TCP listener; the only process that spawns anything
    │      tmux sessions, node-pty attach, durable tasks, file/git operations,
    │      Claude Code introspection, host metrics, hook endpoint
    ▼
         tmux server (socket `-L claude-remote`)
           cr-<uuid>   one per terminal session: `claude …` or a login shell
           crt-<uuid>  one per background task (local, or `ssh <allow-listed node>`)

Details: docs/architecture.md, docs/network-architecture.md, binding engineering contract: docs/CONTRACT.md.

# Repository layout

# Quick start (local development, macOS)

Requirements: Node ≥ 24, pnpm, tmux, a local PostgreSQL with psql/createdb on PATH, and the claude CLI on PATH if you want Claude sessions (shell sessions work without it).

pnpm install
pnpm --filter @cr/web build      # optional: without it dev-up serves the API only
scripts/dev-up.sh                # builds shared/runtime/server, creates + migrates claude_remote_dev,
                                 # starts both processes on http://localhost:8620
cat /tmp/cr-dev-data/setup-token # one-time token for the first-run page (/setup/)
scripts/dev-down.sh              # stops both and kills ONLY the dev tmux server (claude-remote-dev)

dev-up.sh uses /tmp/cr-dev-data (data), /tmp/cr-dev-workspace (workspace root), database claude_remote_dev and its own tmux socket. It never sets CR_INSTALL_CLAUDE_HOOKS, so your ~/.claude/settings.json is not modified and sessions do not report WAITING_FOR_INPUT in this mode.

# Tests

Last recorded results (laptop, 2026-11-10): runtime 209 passed · server 175 passed (17 against the real runtime) · web unit 12 passed · Playwright 19 passed against the mock (15 Chromium desktop, 4 WebKit iPhone 15 emulation) and 2 passed against the real backend · scripts/ci.sh green.

# Deployment summary

Deployed with the cluster orchestrator mld from the gateway (M1M32), pinned to M5M36:

• PM2 processes claude-remote-runtime, claude-remote-server (port 8620), claude-remote-backup (nightly, 03:35);
• PostgreSQL 17 on loopback (role and database claude_remote);
• code in ~/apps/claude-remote (git clone; the node directory is the source of truth), data in ~/claude-remote-data (0700), workspace root ~/workspace;
• public route https://claude.spboucher.ai → Caddy (BHS64) → WireGuard → M5M36:8620.

Updating is done on the node (edit, build, migrate, restart, commit, push): see docs/deployment.md.

# Status of the 17 deliverables

Detail, files, tests and limitations per item: docs/deliverables-status.md.

# Documentation index

# Limitations / not verified

• Not verified on a real iPhone (Safari or installed PWA); emulation only.
• The laptop-independence test has not been run.
• Passkey login has not been exercised in a real browser.
• WAITING_FOR_INPUT has not been observed from a real (paid) Claude conversation; the hook relay itself is tested end to end with the real hook script.
• Web Push is not implemented (in-app notifications only). Skills-registry install is not implemented (501).
• There is no dedicated LaTeX / Jupyter / research feature; a PDF file preview exists in the editor, nothing more. TeX is not installed on the node.
• No local model endpoint exists on the cluster; the Local Models panel is empty by design.
• The application runs under the cluster operator's macOS account, not a dedicated OS identity (see docs/security.md).
• Single host: if M5M36 is down the service is down. Backups currently stay on M5M36.
• No hosted CI; scripts/ci.sh is run by hand. The root lint script references ESLint, which is not configured in this repository.