khang5687/agent-scripts/agent-broker

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 acme = Acme'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

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:

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:

~/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.

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):

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

shows a container's environment). The Linux broker stops accidental .env reads, not a determined agent; a real wall means taking the agent user out of both groups.