byre/docs/operations.md

Operations

Layout

• cmd/byre: byre serve runs the server; byre run drives one Claude session in the current directory from the terminal.
• api/openapi.yaml is the API source of truth. go generate ./internal/api regenerates internal/api/api.gen.go, whose types are also the store's model types.
• internal/store: SQLite (WAL). Every mutation and its event commit in one transaction; events are published to SSE subscribers in seq order.
• internal/server: HTTP handlers, identity, SSE.
• internal/git: worktree create and remove.
• web/: the SPA, embedded into the binary. byre serve --dev serves ./web from disk instead (run from the repo root).

Data

State lives in the byre directory under Go's os.UserConfigDir() (on macOS, ~/Library/Application Support/byre): byre.db and worktrees/<project-id>/<task-id>. Task branches are byre/<task-id> in the project's repo.

Running as a service

The listen address is listenAddr in cmd/byre/serve.go; it binds loopback only.

go install ./cmd/byre
cp deploy/run.fc.byre.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/run.fc.byre.plist
tailscale serve --bg --https=<port from listenAddr> http://<listenAddr>

byre gets its own HTTPS port on the machine's ts.net name rather than a path under another service: the SPA and API use absolute paths, which break under a path prefix. tailscale serve status shows the URL and what else the machine serves.

After rebuilding: go install ./cmd/byre && launchctl kickstart -k gui/$(id -u)/run.fc.byre. Logs go to ~/Library/Logs/byre.log.

Clients reach tailscale serve over HTTP/2; it proxies to byre over HTTP/1.1 and passes SSE through unbuffered.

Identity

tailscale serve adds Tailscale-User-Login and Tailscale-User-Name to proxied requests. The server accepts API requests only from loopback and only with both headers; anything else gets 401 or 403. The SPA's static files need no identity. Users are created on first request; each sets their commit identity with PUT /api/me.

To call the API locally without Tailscale, send the headers yourself:

curl -H 'Tailscale-User-Login: you@example.com' -H 'Tailscale-User-Name: You' http://<listenAddr>/api/me

Events

GET /api/events is server-sent events: id is the event's seq, data the Event JSON. Reconnecting with Last-Event-ID (EventSource does this itself) or ?after= replays everything after that seq before going live. A client that falls further behind than its subscriber buffer (subscribe in internal/server/hub.go) is disconnected and catches up by reconnecting.