agent-broker

Files (16)

• SKILL.md
• accounts.mjs · broker/bin/
• agent-broker-admin.mjs · broker/bin/
• agent-broker.mjs · broker/bin/
• lib.mjs · broker/bin/
• supabase-ca.pem · broker/bin/
• write-block.mjs · broker/bin/
• cli-guard · broker/guard/
• install.sh · broker/
• package.json · broker/
• sudoers · broker/
• broker.test.mjs · broker/test/
• agent-broker · broker/wrappers/
• agent-broker-admin · broker/wrappers/
• lookup.mjs · scripts/
• wizard.sh · scripts/

SKILL.md (first lines)

# Agent broker

The owner has several logins per service. Tokens live only in the **broker** (user `_deployer`, unreadable to
agents). Two layers:

- **Account stack**: one login per service (e.g. stack `thedoor` = theDoor's Netlify + Supabase; stack `global` = default fallback for general projects). Tokens stored once.
- **Project**: a folder, its stack, and the one site / database it may touch (pinned). Nothing else: build folders and
  other settings stay in the project's own files (`netlify.toml`, `vercel.json`, `.actor/`, `supabase/config.toml`),
  read by the real CLI on every call.

**The folder picks the project.** Run `agent-broker` from inside the project folder. Never name an account, site id or
project ref. `gh` is separate (one GitHub account, logged in normally, never touched or logged out by the broker).
## Use it

```sh
agent-broker whoami      # this folder's project, stack, site, database
agent-broker help        # every action
agent-broker <service> <action> [options]
```

- **Deploy**: build as yourself first, then `agent-broker netlify deploy --message "..."` (a draft). It runs
  `netlify deploy --no-build` on the pinned site: netlify.toml `publish` picks the folder, or pass `--dir out`;
  `--prod`, `--alias`, `--functions`, `--json` ... pass through (`agent-broker help`). Add `--prod` only when the owner
  asks (credits). Vercel: `mkdir -p .vercel && agent-broker vercel settings > .vercel/project.json`, `vercel build`,
  `agent-broker vercel deploy`.
- **Supabase**: `query "select ..."` is read-only; `migrate [--dry-run]` applies `supabase/migrations`; any other
  write is `admin-query "..."`, which waits: ask the owner to run `agent-broker-admin approve <id>`, then
  `agent-broker result <id>`.
- **Apify**: `push [--dir <actor folder>]`, `info|builds|runs <actor>`, `logs <run-id>`, `call <actor> --input-file F`,
  `pull <actor> | tar -x`.
- **Plain CLIs** (`netlify`, `supabase`, `apify`, `vercel`) do local work only (`netlify dev`, `supabase start`,
  `vercel build`); account commands stop with a pointer here. For owner manual CLI work with personal global logins,
  pass `--global` (e.g. `netlify deploy --global`) or set `export AGENT_BROKER_BYPASS=1`.
- **Scripts that need a token while running** (nightly jobs, backups) run on GitHub Actions: `gh workflow run ...`.
- **Tokens stay unread**: `.env` secrets, token files, CLI configs, `~/Secrets/*.kdbx`. Never put one in a file,
  argument, log or reply.
- **Errors** "no ... token" or a missing action: stop and ask the owner to run the wizard. `--project NAME` exists
  only for a folder that holds two projects (the error names them).
- **`agent-broker-admin`** is the owner's: it makes a Touch ID prompt on their screen. Run it only when asked.

## New project

"Not inside a registered project" means a new project. Ask the user which stack (`agent-broker stacks`); if a stack
named `global` exists, omitting `--stack` defaults to `global`. In the project folder:

```sh
agent-broker init [--stack <name>] --list    # the stack's sites / databases, and which are free
agent-broker init [--stack <name>] [--netlify-site ID | --netlify-new NAME] [--supabase-ref REF] [--apify]
agent-broker attach --supabase-ref REF       # later: add a service the project does not have yet
```

- `init` registers the git repo root (`--here`: this exact folder) and writes the block into the project's
  `AGENTS.md` / `CLAUDE.md` (refresh: `agent-broker agents-md --write`). No owner approval: it only claims a folder
  nobody owns, on an existing stack, with a site / database of that stack's account that no other project uses.
- `--netlify-new` creates a free Netlify site. A new Supabase project costs money: ask the user to create it on
  supabase.com, then `attach --supabase-ref`. A Supabase ref also gets a read-only database user (`--no-reader` skips).
- A stack that does not exist yet, or lacks a token: the owner adds it with the wizard (menu 1 or 2).

## Owner: the wizard

In your own Terminal app:

```sh
~/git/agent-scripts/skills/agent-broker/scripts/wizard.sh
```

Menu: 1 Add an account stack · 2 Replace a token (one place, every project on the stack) · 3 Add a project
(optional; agents use `init`) · 4 Move a project to another stack · 5 Add a folder (second clone) · 6 AGENTS.md text ·
7 Set up / update. Each save asks for Touch ID once. Git worktrees of a registered repo work without adding them.

Setup / update installs `broker/` to `/opt/agent-broker` (own Node and CLIs), `/usr/local/bin/agent-broker{,-admin}`,
the sudo rule `/etc/sudoers.d/agent-broker` (password every time), and the CLI guard (`/opt/agent-broker/guard`, first
in `PATH` via one line in `~/.zshenv` and `~/.zshrc`). Owner bypass for a real CLI: its full path (`which -a netlify`).
Changing the broker: edit `broker/`, `cd broker && npm test`, then wizard → 7.

## Linux (homelab): Docker Compose

On Linux the broker runs **only** `docker compose` (the cloud CLIs need the macOS sandbox; `netlify` etc. are refused).
A compose stack folder is a project; its secrets live in the broker, its `.env` keeps only non-secret settings.

```sh
agent-broker compose ps | up -d | logs --tail 100 app | pull | down     # instead of docker compose, in the stack folder
agent-broker compose --profile mcp up -d                                 # -f F, --profile, --dry-run before the command
agent-broker compose exec -T db psql -U app < dump.sql                   # stdin passes through; use -T
```

- Runs in the registered folder only (never a git worktree of it: same Compose project name = live containers).
  `--env-file`, `-p`, `--project-directory` are not offered; drop `--env-file .env` from old runbook commands.
- Plain `docker compose` there fails on `${VAR:?set VAR}`: that is the cue to use the broker. `docker logs <container>`
  and `docker ps` need no secrets.
- Output is scrubbed of stored values; `compose config` shows `[secret]`.

Owner setup (once per host, in your own terminal; sudo asks your password):

```sh
sudo ~/git/agent-scripts/skills/agent-broker/broker/install.sh     # _deployer (owner's group + docker), /opt/agent-broker
agent-broker-admin apply --stack homelab --new-stack                 # a stack with no cloud tokens
cd <repo>/stacks/<name> && agent-broker init --stack homelab --here --no-agents-md   # agents may do this step
agent-broker-admin import <name> .env KEY1 KEY2                      # moves the secret lines out of .env
chmod 640 .env                                                      # _deployer reads the non-secret rest
agent-broker-admin set <name> KEY                                    # one value, typed hidden
```

`import` reads values the way Compose does (quotes, `$$`, ` # comment`); a value with a `$` Compose would expand is
refused: use `set`. Update the broker: `git pull`, rerun `install.sh`.

## Known gaps

- **Folder rule = accident prevention**, not a wall: an agent can `cd` into another project's folder.
- **Touch ID for sudo** is on: an unexpected sudo prompt is an agent asking; deny it.
- **GitHub secrets** (`apify-analytics`, `FitUp`): a pushed script could print a secret in an Actions log. Fix: a
  GitHub bot account for agents (write, no admin), `main` protected with owner approval, secrets in an environment
  limited to `main`.
- **Apify actor runs** get a run token; actor code can print it.
- **Netlify** tokens open the whole account; edge-function bundling during a deploy may run project code with the
  token present (no project uses edge functions yet). CLIs run in a macOS sandbox that cannot read the broker's
  token files, so a path in `netlify.toml` (or any project config) cannot point a deploy at them.
- **Tokens agents saw before the broker** (2026-10) stay valid until rotated (wizard → 2).
- **Linux: `docker` / `lxd` group = root.** An agent user in those groups can read any secret back (`docker inspect`

From Khang5687/agent-scripts, MIT.

More from Khang5687/agent-scripts