Skip to content

Clauster

Clauster is a self-hosted FastAPI + Alpine/Tabler web app that spawns and manages claude remote-control bridges on a remote host, driven entirely from the browser. Point it at a directory of projects, click Run Claude here on a project card and choose In claude.ai / Desktop, then pick the bridge up from claude.ai/code or the Claude mobile app — no SSH session required.

It is published to PyPI as clauster, shipped as a signed GHCR container image, and released as Sigstore-signed GitHub Releases.

The two bridge modes

A "bridge" is a claude process that Clauster launches in a project directory and exposes to the Claude remote-control controller. Clauster supports two launch modes, selected per instance via claude.launch_mode. They are not interchangeable — each has its own argv and readiness logic.

Server Mode (default) Interactive Session (opt-in)
Command form claude remote-control (subcommand) claude --remote-control (flag)
Sessions multi-session server single session
Restart behaviour spawns a fresh, empty context — no conversation resume genuinely restores prior context (--continue true resume)
Process model headless server runs under a PTY keeper sidecar that owns the PTY
Platform all POSIX pty, or a Windows ConPTY keeper with the pty extra (else falls back to Server Mode)

The mode is recorded on a bridge at launch: editing claude.launch_mode seeds the mode for new bridges only and never re-modes a running or stopped one (stop/resume always honour the recorded mode).

For users on Server Mode who still want continuity across a restart, the opt-in claude.resume_recap SessionStart hook recaps the most recent prior transcript for the directory back into a freshly restarted bridge. Unlike Interactive Session mode, this recaps the prior conversation rather than truly restoring it.

Key features

Projects & bridges

  • One card per child directory of your projects_root, plus a card for each additional bridge or session a project is running or has stopped.
  • Run Claude here (launch) / Stop / Resume a bridge from the card. For a deliberate fresh start, Forget a stopped session (drops it from Recent), then relaunch.
  • Per-card Open in Claude link and QR code to attach from anywhere.
  • Spawn modes (same-dir, worktree, session) and permission modes (default, plan, acceptEdits, auto, dontAsk, bypassPermissions).
  • Create or clone projects into projects_root with progress streamed over a WebSocket.

Visibility & editing

  • Live bridge debug-log tail over a WebSocket — ANSI-stripped and ID-redacted.
  • In-dashboard editor for a project's Claude Code config surfaces — CLAUDE.md, settings.json (env as friendly key/value rows or raw JSON), permissions (allow / deny / ask rules and default mode as rows, or raw JSON), hooks (one command hook per row — event / matcher / command / timeout — or raw JSON), MCP servers, subagents, skills, and plugins — at user / project scope (plus local for all but subagents and skills), with secret-shaped values masked on the surfaces that carry them (settings env, MCP). Every write is lost-update-guarded and trust-gated; every write is audit-logged to config_audit.log.
  • Approximate per-project cost / token badge rolled up from session transcripts.
  • Live per-bridge resource metrics (CPU / memory / disk) while a bridge runs.

Safety

  • Workspace trust — starting a bridge in an untrusted directory prompts a just-in-time confirm that writes the Claude workspace-trust flag before spawning. Trusted directories show a green shield and start with no prompt.
  • Auto-enable remote control — before the first spawn, Clauster acknowledges remote control in the runtime user's ~/.claude.json so a detached-stdin bridge isn't stuck on the one-time interactive prompt.
  • Fail-closed auth & networking — binding beyond loopback is refused unless authentication is actually enforced.

Opt-in extras

  • Conversation recap on restart (claude.resume_recap).
  • Native Interactive Session mode (claude.launch_mode: pty).
  • Ghost-environment reaper (CLI always available; dashboard gated by reaper.ui_enabled).
  • Dashboard login shepherd (login_shepherd.enabled, default off) — when the runtime claude account logs out or its token expires, sign it back in from the browser (subscription OAuth, plus a separately-gated long-lived setup-token mode) instead of SSHing in. See the login_shepherd reference.
  • Background agents (experimental) — list / dispatch / stop claude --bg sessions from a dashboard panel (/api/agents); rides Claude Code's agent-view research preview, so it may change with the upstream CLI.
  • Hosted Here in the browser channel (experimental) — when the claustrum channel is enabled (claustrum.enabled, default off), the launch popover gains a third option whose sessions are local live-view only: streamed in the dashboard but, unlike bridges, never attachable from claude.ai/code. See Architecture and Configuration.

Where to next

  • Quickstart — your first bridge in a few minutes.
  • Installation — ten install methods with a decision table, plus running and service setup.
  • Configuration — the complete clauster.yml reference.
  • Public API — the versioned /api/v1 surface and clauster api-token CLI.
  • Security — trust model, auth, redaction.
  • Privacy — what Clauster keeps on disk, and how to purge it.
  • Networking — the loopback / non-loopback auth matrix.
  • MCP server — the read-only clauster mcp stdio server.
  • Architecture — module map and bridge lifecycle.
  • Operations — monitoring and the operational runbook.
  • Troubleshooting — symptom-first fixes, with the exact error strings you can search for.

Stack

Python 3.11+ · FastAPI · Alpine.js + Jinja2 + Tabler · uv · pydantic. Developed and CI-gated on Linux; macOS / Windows are in the test matrix. Apache-2.0 licensed.