A tiny, dependency-light Go daemon that hosts a remote Claude Code session over SSH —
a local CLI-version manager + process supervisor + JSON-RPC multiplexer (with a replay
buffer) over a Unix socket. An independent, clean-room implementation you can run yourself.
Independent & unaffiliated. claustrum is a clean-room implementation. It is not affiliated with, authorized by, or endorsed by Anthropic. "Claude", "Claude Code", and "Claude Desktop" are trademarks of Anthropic, PBC, used here only to describe interoperability. See NOTICE.
When you drive a remote Claude Code session over SSH, a small Go daemon runs on the remote host. It isn't a network relay — it's local plumbing:
- CLI-version manager — downloads/verifies/extracts the pinned
claudeCLI, prunes old versions. - Process supervisor — spawns and manages the agent (and any MCP-server) child processes, owning their stdio.
- JSON-RPC multiplexer — speaks newline-delimited JSON-RPC 2.0 over an
AF_UNIXsocket, fanning many clients/streams over one connection, with a replay buffer so a late or reconnecting client can catch up.
claustrum is a from-scratch, behaviorally-compatible implementation of that daemon, so it can
be used independently — e.g. as a building block for self-hosted tooling like
clauster. It produces byte-identical JSON-RPC
frames for every method, apart from a small set of documented, deliberate divergences (see
docs/DIVERGENCES.md).
Status: stable (v1.0+). The JSON-RPC/process/file/git surface is complete and validated; the CLI-version installer is implemented and behavior-checked. No telemetry, ever.
Requires Go 1.25+. Dependencies: github.com/klauspost/compress (zstd, cross-platform), plus
two modules compiled into Windows builds only — golang.org/x/sys (Job Object teardown) and
github.com/Microsoft/go-winio (the opt-in -listen-pipe named-pipe transport, CT-5).
# build the native binary
make build # -> ./claustrum (CGO off, -trimpath, stripped)
# or cross-build all six targets into ./dist/
make all # linux/darwin/windows × amd64/arm64
# or straight go
go build -o claustrum .
go install github.com/schubydoo/claustrum@latestclaustrum -version prints claustrum <version> (built <iso8601>) — a local go build stamps
the SHA and time from embedded VCS build info, a released binary carries its tag, and
go install …@vX.Y.Z reports the resolved module version plus the tagged release timestamp
(buildstamp.go; a pseudo-version like @main prints built unknown).
A go install binary is not flag-for-flag identical to a release artifact (host cgo defaults, no
-trimpath, unstripped). Pass the release flags for an equivalent build:
CGO_ENABLED=0 go install -trimpath -ldflags="-s -w" github.com/schubydoo/claustrum@latestOne binary, mode-switched by flag:
claustrum -serve -socket <path> -token-file <path> # self-daemonize, run the RPC server
claustrum -bridge -socket <path> # dumb stdio<->socket relay (what SSH attaches)
claustrum -stop -socket <path> # ask a running daemon to shut down
claustrum -install -cli-dir <dir> -cli-version <v> [-cli-url <url> -cli-checksum <sha256>] [-cli-zst <file>] [-cli-keep <n>]
claustrum -version
# 1. a private socket + auth token
D=$(mktemp -d); TOK=$(uuidgen); printf '%s' "$TOK" > "$D/token"
# 2. start the daemon (self-daemonizes; reads + unlinks the token file)
claustrum -serve -socket "$D/rpc.sock" -token-file "$D/token" &
# 3. speak JSON-RPC over the socket (auth is in-band, per request)
# reuse the token generated in step 1 (the daemon unlinked the file when it read it)
printf '{"jsonrpc":"2.0","id":1,"method":"server.ping","auth":"%s"}\n' "$TOK" \
| socat - UNIX-CONNECT:"$D/rpc.sock"
# -> {"jsonrpc":"2.0","id":1,"result":{"pong":true}}
# 4. enumerate everything the daemon implements
printf '{"jsonrpc":"2.0","id":2,"method":"server.capabilities","auth":"%s"}\n' "$TOK" \
| socat - UNIX-CONNECT:"$D/rpc.sock"
# 5. shut it down
claustrum -stop -socket "$D/rpc.sock" # no token needed: shutdown is unauthenticatedMore worked examples — spawning a process and reading its base64 output stream, reattaching to catch up via the replay buffer, extracting a plugin tarball — are in docs/PROTOCOL.md and docs/EXAMPLES.md.
- Transport: NDJSON over
AF_UNIXSOCK_STREAM(mode0600); one persistent connection; requests dispatched concurrently. - Auth: every request carries an in-band
"auth":"<token>". The daemon's token comes from-token-file(read once, then unlinked) or-token-fd(read from an open descriptor — the handoff never touches disk). claustrum readsCLAUDE_RPC_TOKENnowhere, and strips it from spawned children. The one exception to auth itself isserver.shutdown, which is not authenticated (matching the reference), so-stopsends no token at all. - 19 methods across
server.*,files.*,git.*,process.*(server.capabilitiesself-describes them). - process.* is the core: a client supplies its own
idonspawn; the daemon streams id-less{"type":"stream",…}notifications (base64 stdout/stderr + anexit), buffers them, and replays onreattach{fromSeq}. This is how both the agent and MCP servers are hosted.process.spawn/process.reattachalso accept"wantPid":true(CT-1), which addspid+startTimeto the result for PID-reuse / orphan detection; a client that doesn't opt in sees byte-identical frames.
Claustrum-only, off the wire: CLAUSTRUM_LOG_LEVEL raises the leveled-stderr log threshold
(logging is always on); -metrics-addr opts into a local Prometheus /metrics endpoint (no
listener exists without it); -keep-children (CT-2, POSIX-only) leaves spawned children running
across a graceful shutdown; -listen-pipe (CT-5, Windows-only) additionally serves the same
JSON-RPC over a named pipe; -wire-log (CT-3) appends every JSON-RPC frame to a file for
diagnostics, redacting credentials by key only. All are off by default.
Seven flags opt into a deliberate divergence from the reference — each is off by default and
has a matching claustrum.conf key (the reachable knob when Claude Desktop owns the argv, a
driver claim — see
docs/ARCHITECTURE.md → Driver claims and their provenance).
See docs/DIVERGENCES.md for the catalog, rules, and measurements.
| Flag | Default | Opts into | Scope |
|---|---|---|---|
-max-extract-bytes (D3) |
off (0) | a files.extract_tar size cap (error frame when exceeded) |
-serve |
-files-read-regular-only (D4) |
off | refusing a non-regular files.read (-32602) |
-serve |
-git-timeout (D5) |
off (0) | a deadline on every git call (-32603 signal: killed) |
-serve |
-max-cli-bytes (D10) |
off (0) | a size cap on the decompressed CLI + download body | -install |
-cli-probe-timeout (D11) |
off (0) | a deadline on the <cli> --version runnability probe |
-install |
-cli-download-timeout (D12) |
off (0) | a deadline on the CLI download | -install |
-libc-probe-timeout (D14) |
off (0) | a deadline on the ldd --version libc probe |
-install, linux only |
Full details: docs/PROTOCOL.md and docs/ARCHITECTURE.md.
Cross-compiles to linux, macOS (darwin), and windows on amd64 and arm64 (6
targets). It's a static CGO_ENABLED=0 Go binary. OS-specific behavior (daemonize, process
groups on Unix / Job Objects on Windows for whole-tree kill, login-shell PATH extraction, the
Windows-only -listen-pipe transport) is isolated in *_unix.go / *_windows.go files; the
JSON-RPC surface is identical everywhere.
claustrum is checked against a reference daemon with a request battery that exercises every
method, error path, and the full process lifecycle, then diffs normalized frames. Current status:
byte-identical on every method the battery exercises, apart from the documented, deliberate
divergences — catalogued in
docs/DIVERGENCES.md — most opt-in and off by default, a few
always-on or conditional. The battery harness lives in scratch/ (local, not
published).
An in-repo test suite (run in CI on every PR, on linux, macOS, and Windows) locks the same contract without the reference binary: a socket-integration battery boots the daemon and asserts every method's frames against committed golden fixtures, alongside unit tests for the install pipeline and the bridge/stop clients (~98% statement coverage). See docs/UPSTREAM-TRACKING.md for how compatibility is kept in sync over time.
See CONTRIBUTING.md. Issues and PRs welcome.
See SECURITY.md for the threat model and how to report a vulnerability privately.
Apache License 2.0 · © 2026 Schuby. See NOTICE for the independence & trademark statement.