diff --git a/docs/operations.md b/docs/operations.md index fa2778a..37187ce 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -6,7 +6,7 @@ What reading byre's code won't tell you: external setup, vendor and platform qui State lives in the directory given by `byre serve --data`, by default `~/Library/Application Support/byre`: `byre.db` (SQLite, WAL), task worktrees under `worktrees/`, uploaded images under `blobs/`. Task branches are `byre/` in the project's repo. This directory is private to the service's OS user (0700), including on existing installations: it contains transcripts, credentials and local agent listener bearer URLs. Other processes running as that same OS user remain trusted. -Migrations are the files in `internal/store/migrations/` (`NNN-name.sql`), plus Go data migrations in `goMigrations`. The number only orders; a migration is identified by its name. A migration's SQL is fixed once applied anywhere: write it out in full rather than sharing Go constants that later change. byre is deployed from task branches that each add their own migrations, so after a merge a migration can land before others the database has already applied, and it still runs. Give a new migration a name no other branch will use, and make any data migration safe to run twice. `sqlite3 byre.db 'SELECT * FROM migrations'` lists what has been applied. +Migrations are the files in `internal/store/migrations/` (`NNN-name.sql`), plus Go data migrations in `goMigrations`. The number only orders; a migration is identified by its name. A migration's SQL is fixed once applied anywhere: write it out in full rather than sharing Go constants that later change. Concurrent task branches can each add migrations, so after a merge a migration can land before others the database has already applied, and it still runs. Give a new migration a name no other branch will use, and make any data migration safe to run twice. `sqlite3 byre.db 'SELECT * FROM migrations'` lists what has been applied. ## Worktrees @@ -67,7 +67,7 @@ byre.run and byre.team are registered at Porkbun, with Cloudflare as their DNS, ## Agent vendors -A model's name picks its vendor: `gpt-*` runs on Codex, `gemini-*` on Antigravity, everything else on Claude Code. Each vendor's protocol is in `docs/claude-protocol.md`, `docs/codex-protocol.md` and `docs/antigravity-protocol.md`. +Vendor setup and protocol quirks are in [Claude Code](claude-protocol.md), [Codex](codex-protocol.md) and [Antigravity](antigravity-protocol.md). - Every agent CLI starts in its own process group, and killing one kills the whole group. Otherwise a launcher that runs the real agent as its child, along with the agent's MCP servers, can keep holding byre's stdout pipe, and the kill waits forever for end of file. - Codex runs with its own home, `codex` under the data directory (`CODEX_HOME`), so the human's `~/.codex/config.toml` (its `notify` program, MCP servers and plugins) doesn't apply and byre's threads stay out of the ChatGPT app's history. That home needs its own login, once: `CODEX_HOME="$HOME/Library/Application Support/byre/codex" codex login`. Until then a Codex turn fails with `401 Unauthorized`, filed as a session error. @@ -104,8 +104,6 @@ byre never signs with a key on the machine it runs on. When a project checkout's ## Client Macs -Task agents use the Macs the human has byre's app open on. - - The app pings every 10s and reconnects after 25s with no pong. That catches a socket byre dropped while the Mac slept: the close never reached the Mac, and without something sent on it the app would wait on it indefinitely. - `log show --info --last 10m --predicate 'subsystem == "run.fc.byre.mac"'` on a client shows `client request : ` lines and `byre-hands` starts and exits, which are info level and kept only in memory, so they cover the last few minutes at most; connection drops (`client connection closed`, `client connection got no pong`) are notices, kept on disk, so `log show --start` reaches much further back for them. byre's log shows `client connected` and `client disconnected`.