Skip to content

README.md

Latest commit

 

History

History
94 lines (67 loc) · 3.38 KB

README.md

File metadata and controls

94 lines (67 loc) · 3.38 KB
Raw

ClaudeBox

Your own Claude Code agent, always on, reachable from your phone.

A box in the cloud runs Claude Code sessions you can open from the Claude app — no laptop required, nothing to keep awake.

Two commands

ClaudeBox is two binaries because it does two unrelated jobs.

cbx-setuptool runs on your laptop and prepares a machine. Interactive: it shows progress, asks for tokens, and hands you the Claude sign-in.

cbx runs on the box and manages sessions. Non-interactive: it never prompts, never reads stdin, and prints one tab-separated fact per line, because its caller is the Claude session itself.

See docs/two-binaries.md for why.

Getting started

Create an Ubuntu machine with your SSH key on it — a DigitalOcean droplet, or anything you can ssh root@ into. Then, from your laptop:

GOOS=linux GOARCH=amd64 go build -o cbx-linux ./cmd/cbx
go build -o cbx-setuptool ./cmd/cbx-setuptool

./cbx-setuptool setup --host <ip> --binary ./cbx-linux

That installs the tool chain, puts cbx on the box, signs Claude Code in, authenticates gh/vercel/supabase from tokens, and copies your skills and settings across. Each step is skipped if already done, so re-running after a failure is cheap.

Then start the always-on session and open its URL on your phone:

ssh root@<ip> cbx new master

cbx — on the box

cbx new <name> [--repo owner/repo]   start a session, print its Remote Control URL
cbx ls                                every session, and whether it is running
cbx resume <name>                     a running session's URL and attach command
cbx kill <name>                       stop it and forget it
cbx export skills|rules|db            what this box has, to stdout

Sessions are recorded in SQLite, so a session that dies is reported stopped rather than vanishing, and a Remote Control URL survives a tmux restart.

cbx-setuptool — on your laptop

cbx-setuptool setup   --host <ip> --binary <linux-cbx>   the whole flow
cbx-setuptool auth    --host <ip> [github|vercel|supabase]
cbx-setuptool migrate --host <ip>    push ~/.claude skills, agents, settings
cbx-setuptool status  --host <ip>    what is installed and authenticated

Tokens are piped over SSH into each tool's own login rather than passed as arguments, where they would be visible in the box's process table. A token already in your environment (GH_TOKEN, VERCEL_TOKEN, SUPABASE_ACCESS_TOKEN) is used without asking.

settings.json is rewritten on the way: paths under your home directory are remapped, and hooks calling binaries the box does not have are dropped and reported. Copied verbatim they would fail on every edit inside every session.

Testing

go test ./...              # unit and integration, drives real tmux and SQLite
scripts/smoke.sh --create  # provision a real droplet, drive it, destroy it

cbx has no remote dependency, so it is fully testable on a laptop. The smoke test exists because fakes cannot model a shell, a PATH, an installer that exits 0 having done nothing, or Claude asking to trust a folder — every serious bug in this project was found by running against a real box.

Docs