unsolo helper

Tiny local daemon (one file, no deps) that lets unsolo route your turns through the claude CLI on your own machine. That way the model call uses your Claude Pro/Max plan (or your own API key) — not unsolo's shared key.

Why? unsolo runs in the cloud and pays for Claude on your behalf by default. Power users with their own Pro/Max plan can install this helper to spend their own quota instead. Mixed-team rooms work — each user's turns route based on whether they installed the helper.

How it works

browser (joinunsolo.com)  ──HTTP──►  helper (127.0.0.1:7842)  ──spawn──►  claude -p ...
                                                                      ↓ uses your
                                                                        Keychain /
                                                                        ~/.claude
                                                                        credentials

The helper is a localhost web server with three endpoints. The browser checks for it, sends prompts to it, streams responses back over SSE, and posts the result into the shared room — same shape as a server-routed turn, just with the model call happening on your laptop.

Quick start

You'll need Node 20+ and the claude CLI installed and signed in.

# Install Claude Code once, log in once (Pro/Max OAuth or API key):
npm install -g @anthropic-ai/claude-code
claude login

# Then start the helper from any terminal:
npx unsolo-helper start

Visit /helper in unsolo and click Pair helper. Done.

Commands

| Command | What it does | | ----------------------------------------- | --------------------------------------------------------- | | npx unsolo-helper start | Start the daemon detached. Survives terminal close. | | npx unsolo-helper start --foreground | Run in this terminal instead — useful for debugging. | | npx unsolo-helper stop | Stop the running daemon. | | npx unsolo-helper status | Print whether a daemon is currently running. | | npx unsolo-helper pair | Mint a device token without starting the server. | | npx unsolo-helper reset | Clear the saved token. Next start re-pairs from zero. |

Detached start writes its PID to ~/.unsolo/helper.pid and tees stdout + stderr into ~/.unsolo/helper.log. stop reads the pidfile and sends SIGTERM (then SIGKILL after 5s if it had to). Reboots are not handled — run start again after a reboot, or wire it into launchd / systemd / a Windows scheduled task if you want true autostart.

(While developing locally from the repo, substitute node helper/index.js for npx unsolo-helper.)

Endpoints

All requests must come from an allowlisted origin. Defaults:

• http://localhost:3000, http://127.0.0.1:3000 — local dev
• https://joinunsolo.com — production
• https://*.joinunsolo.com — preview subdomains
• https://*.onrender.com — Render preview deploys

* matches a single DNS label (letters/digits/hyphens, no dots), so https://a.b.onrender.com and https://x.onrender.com.evil.com are both rejected. Override the whole list with a comma-separated UNSOLO_ALLOWED_ORIGINS.

• GET /status — open. Returns {ok, version, paired, binary, claudeReady}. claudeReady is a best-effort signal: it's true when the helper can find Claude Code's stored credentials (~/.claude/.credentials.json, or the macOS Keychain entry).
• POST /pair — open if not yet paired; returns {token} once. Refuses with 409 already_paired if a token already exists.
• POST /run — bearer-token-protected. Body: {prompt, systemPrompt?, model?}. Streams Server-Sent Events:
  • event: delta data: {text: "..."}
  • event: done data: {exitCode, stderr, errorCode} — errorCode is "not_signed_in" when the CLI failed because the user is logged out
  • event: error data: {message}

Configuration

| Env var | Default | Purpose | | ------------------------ | ---------------------- | -------------------------------- | | UNSOLO_HELPER_PORT | 7842 | Bind port (always 127.0.0.1). | | CLAUDE_BIN | claude | Path to the CLI binary. | | UNSOLO_ALLOWED_ORIGINS | localhost + joinunsolo.com + render | CSV of allowed Origin values. |

The token lives at ~/.unsolo/device.token (mode 0600). Treat it like a password — anything with that token + a browser tab pointing at joinunsolo.com can drive your Claude plan.

What's not in here yet

• No multimodal (image/PDF) input — text prompts only.
• No tool use / MCP routing — the helper just streams the CLI's stdout back.
• No autostart on reboot. start detaches from your terminal so it survives closing the window, but a full reboot still requires running start again.