# Operations

What reading byre's code won't tell you: external setup, vendor and platform quirks seen live, and the intent behind rules. `api/openapi.yaml` is the API's source of truth; `go generate ./internal/api` regenerates `internal/api/api.gen.go`.

## Data

The data directory must remain private to the service's OS user (0700): it contains transcripts, credentials and local agent listener bearer URLs. Other processes running as that same OS user remain trusted.

Add SQL migrations in `internal/store/migrations/` as `NNN-name.sql`. 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

byre runs nothing in a new worktree. Installing dependencies or copying untracked files such as `.env` is the project's own instruction in its AGENTS.md, carried out by the agent with its own tools.

## Running as a service

The service always runs from the app: `/Applications/Byre.app/Contents/Helpers/byre install`, which the app's Server tab and connection screen run. `byre install` takes `PATH` from the shell it is run in, since the service's `PATH` must find `claude`, `codex`, `agy`, `git`, `curl` and `npx`. When the service is already loaded, `install` hands `launchctl bootout` and `bootstrap` to a detached `sh` and exits: `bootout` kills every process in the service's process groups, which includes `byre install` itself when an agent byre runs is the one running it.

`byre serve` exits when its executable is replaced (logging `executable replaced, exiting`) and launchd starts the new one. A missing path counts as not yet replaced, so the moment in `install.sh` between removing the old bundle and moving the new one in doesn't trigger it. The service log is owner-only (0600), including existing logs: Tailscale can put a sign-in URL there. Logs go to `~/Library/Logs/byre.log`; `launchctl print gui/$(id -u)/run.fc.byre` shows the service.

## Slow requests

An API request that takes 200 ms or more is logged on both ends. The server's line, `request slow`, in `byre.log`, has the handler's time and its spans: each git process, SQL begin, exec and query, the wait for the store's write lock, and the tailnet `whois`. Every response also carries these spans in a `Server-Timing` header. On the client, `log show --start <time> --predicate 'subsystem == "run.fc.byre.mac" AND eventMessage BEGINSWITH "request slow"'` shows the app's line, which splits the request's time into `queue` (waiting for a connection), `connect`, `network` (time to the first byte, less the server's time), `server`, `download` and `app` (how long the main actor took to pick up work once the response ended). Event streams and websockets are left out.

## Tailnet

byre runs its own tailnet node with `tsnet`; it doesn't use the Tailscale app. The app connects at the root of the node's `ts.net` name on 443, not under a path: the API uses absolute paths and the app takes an origin with no path. Tailnet access requires a user identity; a tagged node gets 403. Local scripts can also check server status and run client commands through the authenticated loopback address.

Tailscale identifies the connecting Mac, including requests from a web page opened there; network identity alone doesn't establish the user's intent. Cross-origin browser requests must not be allowed to change state through that identity. Native app and CLI access remains intentional.

Loopback access requires the bearer credential in `<data>/loopback-token`, regenerated on service startup. It grants both server status (including the node's sign-in URL) and command execution on connected client Macs. Keep it private: loopback is reachable by other OS accounts, so the address alone provides no protection.

A new node needs signing in: `curl -H "Authorization: Bearer $(cat "$HOME/Library/Application Support/byre/loopback-token")" <loopback>/api/tailnet` (`byre check` prints the loopback address) shows `NeedsLogin` and the `auth_url`, and the app on the same Mac shows it as **Sign in to Tailscale**. The tailnet must have MagicDNS and HTTPS certificates turned on (the DNS page of Tailscale's admin console); without certificates byre logs `tailnet has no https certificates` and serves only the loopback address until it is restarted.

Each preview gets its own port on byre's node rather than a path under byre's origin, since path-prefix proxying breaks apps that use absolute paths. Previews use the same user-only tailnet trust boundary as the API; tagged nodes are excluded.

## Releases

A release is one notarized disk image, `byre-<version>.dmg`, holding `Byre.app` with the server, `byre-hands` and `byre-update` in `Contents/Helpers`. Images are served from `https://dl.byre.run/`; each release's notes are on `https://g.fc.run/ai/byre/releases`. `mac/package.sh` builds one, `mac/deploy.sh` installs it locally (see `AGENTS.md`, "Deploying"), and `mac/release.sh <notes>` publishes it from a clean checkout at a pushed `v<version>` tag. A deployed build's `CFBundleVersion` is at least the last release's, so the updater never offers to go back to it.

The appcast must never name an image that isn't available yet, and a published g.fc.run release must already have its attachments. If a failed release run leaves a draft on the releases page, delete it there before running again.

It needs, on that Mac:

- a Developer ID Application certificate in the keychain (`security find-identity -v -p codesigning` lists it), with its key's access answered **Always Allow** for `codesign` (the first signing asks for the login keychain password on the Mac's screen, and a prompt left waiting fails that run with "timestamps differ"), and `mac/byre.provisionprofile` being the Developer ID profile for `run.fc.byre.mac` with iCloud (`security cms -D -i mac/byre.provisionprofile` prints it);
- a `notarytool` keychain profile named `byre-notary`, made with `xcrun notarytool store-credentials byre-notary --key <AuthKey.p8> --key-id <id> --issuer <issuer>` from an App Store Connect API key;
- the Sparkle signing key in the login keychain under account `byre` (`~/Library/Caches/byre/sparkle-<version>/bin/generate_keys --account byre -p` prints its public key, which must match `SUPublicEDKey` in `mac/Info.plist`; `-x <file>` exports it for safekeeping). The script downloads Sparkle's tools to that cache directory when they are missing;
- a g.fc.run token that can write the repo's releases, as the generic password with service `byre-release` (`security add-generic-password -s byre-release -a g.fc.run -w <token>`);
- the `cktool` management token (see "CloudKit schema");
- the Cloudflare token (see "Website").

## CloudKit schema

The app's SwiftData store syncs through CloudKit's Production environment. Production never creates fields itself: a record carrying an attribute its schema lacks is rejected, and that one rejection stalls every later upload from that Mac (its `ANSCKEVENT` table shows exports failing with `CKErrorDomain` 2) until the app relaunches after the schema is fixed. So a change to the SwiftData models must be added by hand before it is deployed or released:

1. `xcrun cktool export-schema --team-id <team> --container-id iCloud.run.fc.byre.mac --environment development --output-file <file>` (`<team>` is `TeamIdentifier` in `security cms -D -i mac/byre.provisionprofile`).
2. Add each new attribute to its `CD_<Model>` record type as `CD_<attribute>` (`Int` is `INT64 QUERYABLE SORTABLE`), and each new model as a `CD_<Model>` record type shaped like the others (`CD_entityName`, the `___` system fields and the grants).
3. `xcrun cktool import-schema` the file back to Development, then Deploy Schema Changes in the CloudKit console.

`export-schema --environment production` shows what Production has, and `mac/package.sh` refuses to build while it lacks a model attribute. `cktool` needs a management token saved with `xcrun cktool save-token --type management --method file` (the console's Tokens & Keys page makes one). The CloudKit console (icloud.developer.apple.com, the container, Production, Private Database, zone `com.apple.coredata.cloudkit.zone`) shows the records. CoreData's own log lines redact sync errors; the app logs them in the clear.

## Website

byre.run and byre.team are registered at Porkbun, with Cloudflare as their DNS, in the Cloudflare account `cloudflare@flamingcow.io`.

- `https://byre.run/` (and `www.byre.run`) is the Cloudflare Pages project `byre`, published by `site/deploy.sh`. Releases don't redeploy it; its download link is `https://dl.byre.run/byre.dmg`, which each release replaces.
- `https://dl.byre.run/` is the R2 bucket `byre`'s custom domain, holding what `mac/release.sh` uploads.
- byre.team, and every path on it, redirects to `https://byre.run/` through a redirect rule on its zone (Rules → Redirect Rules in the dashboard), over proxied `AAAA 100::` records for `byre.team` and `www.byre.team`.

`site/deploy.sh` and `mac/release.sh` read a Cloudflare API token from the generic password with service `byre-cloudflare` (`security add-generic-password -s byre-cloudflare -a cloudflare -w`, which prompts for it); it needs Account → Cloudflare Pages: Edit and Workers R2 Storage: Edit, and Zone → DNS: Edit, Single Redirect: Edit, Zone Settings: Edit and Cache Purge: Purge on both zones. byre.run's Browser Cache TTL is "Respect Existing Headers", so browsers keep the short cache on `byre.dmg` and `appcast.xml`.

## Agent vendors

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.
- Antigravity uses the user's own login and config (`~/.gemini`), so its conversations show up in the user's own `agy` history.
- Claude Code records `--append-system-prompt` on a session's first request and reuses it on resume, so a running session keeps the guidance it started with; the `UserPromptSubmit` hook re-attaches the guidance to every turn so existing sessions see changes. On a fork Claude Code can reuse the system prompt recorded for the source conversation, the source's cwd included, so the hook's copy is what reliably tells a fork where it is.
- A Claude `result` with `num_turns` 0, no `result` text and no error, outside an interrupt, isn't a turn end: the CLI emits one on its own, for example after a resume when it reports a background shell left over from the previous process. byre logs `ignored result with no model turns` and keeps the turn running.
- stream-json doesn't expand `@path` the way the interactive CLI does, so the composer has no `@`-file mentions; the agent reads any file a message names with its own tools.

## Agent behavior

- A turn whose final message asks the human something in prose is bounced once, telling the agent to use `ask_human`. For Claude the bounce is a Stop hook that blocks the stop; Claude Code reports the block as a "Stop hook error" notification, which is expected. An agent told explicitly to ask in plain text will refuse the bounce.
- A turn that asks a question has no summary; everything the human needs belongs in the question's context. Other turns use their final message as the summary; don't ask agents to write a second recap.
- A review covers the whole task against the default branch, so a newer one makes older ones moot. Findings reach the task's agent together, once the whole review workflow finishes; an individual reviewer finishing is not a completed review.
- An audit checks only the newest commit of the default branch, one at a time per project, so it doesn't run on every revision but the newest one is always audited eventually. byre never fetches for an audit, so a commit pushed outside byre is audited only once a byre merge has fetched it.
- A team task that comes up with some members failing to start isn't repaired; discard it and create it again.

## Coordination

Coordination of merges, discards, reviews, ready-for-merge prompts, workflow stages, deliveries to lead agents and queued messages, and Merge & continue's hold on teammates must decide from the database's current state, never from which event woke it. This lets startup use the same decisions as ordinary operation rather than maintaining separate recovery logic. Slow work must run outside the decision transaction, with its progress recorded so another pass cannot start it twice.

## git

- Merge notes live under `refs/notes/byre`. byre adds the fetch refspec `refs/notes/byre*:refs/notes/byre*` to each checkout; it's a pattern because git refuses a fetch whose exact refspec names a ref the remote doesn't have yet, as it doesn't before the first note is pushed. Another clone adds it with `git config --add remote.origin.fetch 'refs/notes/byre*:refs/notes/byre*'`; `git log --notes=byre` shows the notes.
- `git fetch` and `git push` run non-interactively (`GIT_TERMINAL_PROMPT=0`, ssh `BatchMode=yes`, overriding any `core.sshCommand`), so a remote needing a password or an unknown host key fails at once instead of waiting for input. Every git command runs in its own process group, killed whole on timeout, so an `ssh` it started can't finish a fetch or push after byre has moved on.
- A push error other than a non-fast-forward rejection is ambiguous, since the remote may have taken the push before the connection dropped; byre then fetches and checks whether the commit landed before deciding.
- The project's checkout must have the default branch checked out: a merge fast-forwards it.

## Signing merges

byre never signs with a key on the machine it runs on: every git command it runs there, except `git config`, gets `-c commit.gpgsign=false`, so its end-of-turn, snapshot and merge-in commits stay unsigned whatever the server's config says. A signing program left to run under the launchd service can wait forever on a prompt nobody sees (`ac-sign` waiting on AppleConnect did), and the turn would never end. Those commits never reach the default branch anyway; the squash replaces them. When a project checkout's `commit.gpgsign` is true (`git -C <checkout> config --type=bool --get commit.gpgsign` prints it), the squash commit of a merge is signed on the merging user's most recently active Mac, so a key that never leaves that Mac's Secure Enclave and needs a fingerprint works. The Mac runs its own git signing config, as git does: `gpg.format` (`openpgp` or `x509`; `ssh` is not supported), the program when it isn't `gpg`/`gpgsm`, and `user.signingkey` when the program can't find the key from the user's byre git identity (not the Mac's `user.email`). The program must print `[GNUPG:] SIG_CREATED ` on its status fd, as git requires. A Touch ID prompt left unanswered for 2 minutes fails the merge. The notes commit is not signed.

`byre signing <checkout>` turns it on for a project; agents learn it from the `signing` knowledge-base article. It sets `commit.gpgsign` true in the checkout; a global `commit.gpgsign` true on the server does the same for every project. Agents' own `git commit` in a task worktree reads that config and runs the signing program on the server. No restart is needed; `git -C <checkout> cat-file commit HEAD` shows the `gpgsig` header.

## Client Macs

- 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 <id>: <op>` 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`.
- `byre client-exec` (how to use it, and `byre screen`, is the `client-exec` knowledge-base article) uses the loopback token, which byre exports as `BYRE_TOKEN` to everything it starts. byre's log has a `client exec` line per call with the client, command, exit status and duration, never the output, since it may hold credentials.

## Screen and app control

- **One path per process.** replayd, the daemon behind ScreenCaptureKit, keys its clients by executable path: two processes run from one path keep canceling each other's connection, and every capture from that path hangs. replayd's log shows it as `accepted client connection PID: <a>` and `invalidated because the current process cancelled the connection` alternating between two pids, thousands of times a second. So each server session runs its own copy of `byre-hands` from its own file, and the app runs one shared by all its connections.
- **Window server.** `NSApplication.shared` connects the process to the window server at startup, without which ScreenCaptureKit asserts. AppleScript needs the main thread with a run loop, so every script runs there.
- **Busy apps.** An app in a menu-tracking loop or otherwise busy answers neither Apple events nor accessibility requests; scripts time out after 10s and accessibility requests after 3s, and the first timeout fails the whole call rather than waiting on every element.
- **Display sleep.** While the display sleeps, ScreenCaptureKit lists no displays. Every call holds a `PreventUserIdleDisplaySleep` assertion and, when the display is asleep, declares user activity and waits for ScreenCaptureKit to list it again. A declared activity doesn't reset the keyboard and mouse idle time, so the display sleeps again after powerd's grace period (`com.apple.powermanagement.delayDisplayOff` in `pmset -g assertions`), not after the full display-sleep delay. `pmset -g log` shows each wake as `Display is turned on` beside `byre-hands` assertions.
- **Orion.** Orion ignores key events that carry only a Unicode string, so typing posts each ASCII character as its key code. Some apps list `confirm` but ignore it, Orion's address bar among them; send Return instead. `do JavaScript` needs Orion's Develop → "Allow JavaScript from Apple Events".
- **Chrome.** Chrome refuses remote debugging on its default profile, so byre's Chrome is its own profile (`~/Library/Application Support/byre/chrome`), a separate Chrome beside any the human runs, and it keeps its logins: the human signs in there once. Chrome comes from `brew install --cask google-chrome`; macOS's "downloaded from the Internet" prompt on its first launch must be answered Open (or `osascript -e 'tell application "System Events" to tell process "CoreServicesUIAgent" to click button "Open" of window 1'`), and until it is, Chrome cannot accept debugging commands.
- **Chrome's trust boundary.** Use Chrome's loopback debugging port with byre's separate persistent profile and Chrome's default browser-origin checks; never add `--remote-allow-origins=*`. Other local OS accounts can reach that debugger and control its logged-in sessions. This is an accepted risk on the personal Macs byre runs on, as is access to the app's local preview forwards; do not add account-isolating brokers for these listeners. Chrome must be launched with `--remote-debugging-port=0` so it records its port and browser WebSocket path in the profile’s `DevToolsActivePort` file. After switching from the pipe or fixed-port transport, quit the old byre-profile Chrome once so the next tool call can start it with that discovery file. The saved profile and logins stay in place.
- **Permissions.** Agents' processes run as byre's descendants, so macOS privacy controls (TCC) hold byre responsible for them: the Screen Recording, Accessibility and Automation grants in System Settings → Privacy & Security are byre's, made by clicking at the Mac's screen, and each app scripted for the first time asks for its own Automation grant. Without Accessibility an untrusted process just sees no windows and no menu bar. Accessibility can list byre switched off; only its switch being on counts. TCC keys grants on the signing identifier and team, and every build is signed with Developer ID, so grants carry over from build to build. On a client Mac the grants belong to byre's app; `NSAppleEventsUsageDescription` in `mac/Info.plist` is what lets macOS ask for the Automation grant. `byre-hands check` prints the grants of the process that runs it; the Server and Settings tabs run it.

## Terminals

- `terminal_type` takes named keys because Claude Code passes tool arguments through as the text the model wrote, so an escape like `\u0003` in `text` reaches the shell as six characters.
- In a new shell it waits for the prompt first: typing earlier would reach the PTY while it still echoes in cooked mode, before zsh's line editor takes over, so the text would show twice. A terminal started from a saved command waits the same way before its command is typed.
- Saved commands belong to a user on one server, because what they do is usually tied to that Mac: signing in again to the credential an `apiKeyHelper` uses (AppleConnect's `getToken -n cli` on a work Mac) is the case they were made for. Its terminal stays open after the command, so the result stays readable.
- zsh gets shell integration through a `.zshenv` in `<data>/zsh` (via `ZDOTDIR`) that reports the prompt (OSC 133) and the line being edited, so byre can wake the agent when a line it left is run. It turns off `PROMPT_SP`, which would print a `%` padded to the width the shell started at, so an agent-opened shell (120 columns) replayed in a narrower tab wraps each one onto an extra line. A user `.zshrc` that sets `zle-line-pre-redraw` with `zle -N` rather than `add-zle-hook-widget` replaces the hook, and byre then sees the line as empty. Other shells get no integration and nothing wakes their agents.