ai/byre
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Add --data, --listen and --ports to byre serve for task previews

Browse Source
This commit is contained in:
Ian Gulliver
2026-10-15 12:39:46 -07:00
parent 8beab6e384
commit 4a9888e653
18 changed files with 100 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/operations.md
+16 -5
View File
@@ -14,7 +14,7 @@
## Data
State lives in the `byre` directory under Go's `os.UserConfigDir()` (on macOS, `~/Library/Application Support/byre`): `byre.db`, `worktrees/<project-id>/<task-id>`, `leads/<login>` (each lead agent's working directory, the login path-escaped), and `blobs/<blob-id>` (uploaded images; the `blobs` table maps each id to its content type and its path relative to this directory). Task branches are `byre/<task-id>` in the project's repo.
State lives in the directory given by `byre serve --data`, by default the `byre` directory under Go's `os.UserConfigDir()` (on macOS, `~/Library/Application Support/byre`): `byre.db`, `worktrees/<project-id>/<task-id>`, `leads/<login>` (each lead agent's working directory, the login path-escaped), and `blobs/<blob-id>` (uploaded images; the `blobs` table maps each id to its content type and its path relative to this directory). Task branches are `byre/<task-id>` in the project's repo.
Schema changes are the `migrations` slice in `internal/store/store.go`: named entries, each with a short kebab-case name saying what it does. On open, byre applies, in slice order, every entry whose name isn't in the `migrations` table, each in its own transaction that also records the name. Each runs with foreign keys off, so a migration can rebuild a table other tables reference, and `PRAGMA foreign_key_check` must come back empty before it commits. byre is deployed from task branches that each append 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. A database from before the table existed is moved over on open: the first `PRAGMA user_version` entries are recorded as applied, and `user_version` is no longer read or written.
@@ -22,7 +22,7 @@ Schema changes are the `migrations` slice in `internal/store/store.go`: named en
Every task worktree is made by `createTask` (`internal/agents/tasks.go`): new tasks, `create_task`, `start_todo` and forks alike.
- **Ports.** Each active task holds a block of `store.PortBlock` ports starting at `tasks.port_base` (`port_base` on the Task). `Store.CreateTask` gives a new task the lowest block from `store.PortFirst` up that no active task holds, so a merged or discarded task's block is reused. The agent's `claude` process gets `PORT` (the first port, which most dev servers read on their own), and the session guidance names the range and says to run dev servers on it. `sqlite3 byre.db "SELECT id, port_base FROM tasks WHERE status = 'active'"` lists the blocks in use.
- **Ports.** Each active task holds a block of `store.PortBlock` ports starting at `tasks.port_base` (`port_base` on the Task). `Store.CreateTask` gives a new task the lowest block from `byre serve --ports` (default `store.DefaultPortFirst`) up that no active task holds, so a merged or discarded task's block is reused. The agent's `claude` process gets `PORT` (the first port, which most dev servers read on their own), and the session guidance names the range and says to run dev servers on it. `sqlite3 byre.db "SELECT id, port_base FROM tasks WHERE status = 'active'"` lists the blocks in use.
- **Setup script.** If the new worktree has an executable `script/setup` (`setupScript` in `internal/agents/setup.go`), byre runs it in the background, in the worktree, with `PORT` added to byre's environment. Nothing in its interface is byre-specific: a script that copies untracked files such as `.env` from the project's checkout finds it as the parent of `git rev-parse --path-format=absolute --git-common-dir`. It is the project's own file, so a branch that changes it changes the setup of tasks started or forked from that branch. It is killed after `setupTimeout`. The task's transcript shows a `setup.started` note and a `setup.ended` note holding the last `setupOutputBytes` of its combined output (`output`), how long it took (`duration_ms`) and `error` when it failed.
- **Waiting.** While setup runs, the task's turns are queued as if the caps were full (`Manager.settingUp`, checked in `turn` and `drain`), so the session shows `queued`; when setup ends, byre drains the queue. Task creation itself doesn't wait.
- **Failure.** A failed setup doesn't stop the agent. The next prompt its session submits gets the failure and the output appended to the `UserPromptSubmit` guidance (`remindTaskGuidance`), and at that moment byre files the same text as a `session_error` inbox item. The setup state and failure live in memory, so a byre restart during setup leaves the queued turn to start without it and nothing reruns the script.
@@ -45,13 +45,13 @@ One merge runs per project at a time. The Manager keeps the task holding each pr
## Running as a service
The listen address is `listenAddr` in `cmd/byre/serve.go`; it binds loopback only.
The listen address is `byre serve --listen`, whose default is in `cmd/byre/serve.go` (`go run ./cmd/byre serve --help` prints it); keep it on loopback, since identity relies on requests arriving from `tailscale serve`.
```
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>
tailscale serve --bg --https=<listen port> http://<listen address>
```
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.
@@ -60,6 +60,17 @@ After rebuilding: `go install ./cmd/byre && launchctl kickstart -k gui/$(id -u)/
Clients reach `tailscale serve` over HTTP/2; it proxies to byre over HTTP/1.1 and passes SSE through unbuffered.
## Previewing byre
A task's build of byre runs alongside the service with its own empty state, from the worktree root, on the task's port:
```
go run ./cmd/byre serve --dev --data "$PWD/.preview" --listen 127.0.0.1:$PORT --ports 51000
tailscale serve --bg --https=$PORT http://127.0.0.1:$PORT
```
It must never share the service's data directory: nothing locks the database, and startup resumes every session marked `running` in its recorded worktree. `--ports` puts the preview's own tasks' port blocks in a range the service's tasks don't use; each instance only knows its own tasks, so with the default both would hand out blocks from the same first port, starting with the one the preview listens on. `.preview/` is gitignored, so the end-of-turn commit leaves it out. The preview starts with no users, projects or sessions; set a git identity with `PUT /api/me` and add a project to try things. A project's Merge pushes to its checkout's `origin`, so a preview project should be a clone whose `origin` is a local bare repository (`git clone --bare <checkout> .preview/origin.git`, then clone that), never the real checkout. `tailscale serve --https=$PORT off` removes the preview's port; `tailscale serve status` lists what is served. byre's own environment doesn't have `tailscale` on its `PATH`; on macOS the CLI is `/Applications/Tailscale.app/Contents/MacOS/Tailscale`.
## 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`.
@@ -67,7 +78,7 @@ Clients reach `tailscale serve` over HTTP/2; it proxies to byre over HTTP/1.1 an
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
curl -H 'Tailscale-User-Login: you@example.com' -H 'Tailscale-User-Name: You' http://<listen address>/api/me
```
## Agent sessions