agentleFS
BariBariGoodBariBariGood/manzanas/.agents/skills/broker-federation/SKILL.md

broker-federation

Skill22 starsChanged 3 months agoApache-2.0View on GitHub

Run manzanas-broker to federate multiple manzanasd daemons behind one endpoint, including daemons only reachable through an SSH tunnel. Use when agents need "any matching simulator in the fleet" placement across several Macs.

The file

Files
SKILL.md

Broker federation

manzanas-broker fronts N daemons (one per Mac) for placement only: target enumeration + lease scheduling. After a grant, ALL target-bound work (boot, actions, streams, state, recording, journal) goes directly against the lease's host_addr — media and actions never flow through the broker. The manzanas CLI and MCP facade follow host_addr automatically, so you can keep them pointed at the broker address for the whole lease lifecycle; only raw curl/HTTP clients must re-point themselves.

Run it

Cross-platform; typically on a Linux box on the same tailnet:

make build
bin/manzanas-broker --addr :7440 \
  --host mac1=http://100.64.0.1:7433,intel \
  --host mac2=http://100.64.0.3:7433,arm64

curl -s localhost:7440/v0/healthz        # {"ok":true,"role":"broker","hosts":N}
curl -s localhost:7440/v0/fleet/hosts | jq   # per-host up/targets/active_leases

Alternatives: MANZANAS_BROKER_HOSTS='mac1=100.64.0.1:7433,intel;...' env (';'-separated) or --config fleet.json ({"hosts":[{"name","addr","labels"}]}). Names/addresses must be unique; static list — restart to add hosts. Run ONE broker per fleet.

Tunneled hosts

For a daemon that is not directly reachable from the broker's box (or bound to localhost), forward it over SSH and register the local end:

ssh -f -N -L 7439:localhost:7433 <user>@<mac-tailnet-ip>
bin/manzanas-broker --addr :7440 --host mac2tun=http://127.0.0.1:7439

Caveat: host_addr handed to clients is then http://127.0.0.1:7439, which only resolves on the broker's machine — either run clients there too, or give each client the same tunnel. Prefer direct tailnet addresses whenever possible.

Federated leasing

POST /v0/leases on the broker takes the normal AcquireLeaseRequest. Labels may include host-level labels (the host name and its configured extras): ["mac2","ios26"] pins the lease to one Mac; host labels are stripped before proxying.

  • 201 → active; the Lease carries host + host_addr — raw HTTP clients talk to host_addr from now on (the CLI/MCP do it for you).
  • 202 → queued on the least-loaded candidate; poll GET /v0/leases/{id} through the broker until active.
  • 409 no_match → no host has a matching target. 503 unavailable → all matching hosts are down (retryable outage, not a label mismatch).

Renew/release/get by lease ID route through the broker to the owning daemon. A broker restart loses its lease→host table — clients that saved host_addr renew/release against the daemon directly (the CLI/MCP client falls back to its cached host_addr automatically); TTL expiry cleans up the rest.

Health

Hosts are probed every --probe-interval (10s default; --probe-timeout 3s). A down host's targets vanish and it gets no new leases; existing leases on it are untouched. No WS surface and no auth on the broker — tailnet-only, never expose publicly.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.