Buddy Agent

What does Buddy do?

farm-buddy (often just “Buddy”) is a single Rust binary you run on any host that should accept builds. It:

1. Connects outbound to Farmland over a secured bus connection (NATS) — no inbound ports, no firewall changes. Works behind any proxy that allows outbound TLS.
2. Advertises which capabilities it covers (e.g. hil, canoe) and what labels it carries (e.g. gpu, arm64).
3. Receives work request events from the Farmland orchestrator and hands them off to Farm Runner for actual execution.
4. Streams logs end-to-end encrypted. Buddy holds the key. Farmland never sees plaintext logs.
5. Reports lifecycle events back to the orchestrator: build started, succeeded, failed, parcel produced. No source code, no artefacts ever leave Buddy.

Buddy is the trust boundary

• No inbound port. All communication is a single outbound connection. No reverse tunnel, no NAT punching, no agent fleet.
• No source code leaves Buddy. Buddy clones your repo locally and hands the working tree to Farm Runner. The orchestrator sees that a build happened, when, on which buddy, and how long it took — but never what got built.
• No root required. Buddy runs as a regular user. If you want per-build isolation, Buddy hands off to your runtime of choice (podman, firecracker, k8s job, …).

Running a buddy

# 1. Register at console.farmland.rocks and create a buddy key
#    (Account → API Keys → New buddy key). Copy the tenant id (hex)
#    from the user menu — that's what '--tenant' takes below.

# 2. Pull the binary
$ curl -L https://www.farmland.rocks/dl/farm-buddy/latest -o farm-buddy
$ chmod +x farm-buddy

# 3. Drop the key at the XDG default path (0600 required — buddy
#    refuses to read a group/other-readable key file):
$ mkdir -p ~/.config/farmland
$ install -m 600 /dev/null ~/.config/farmland/buddy.key
$ printf '%s' "$YOUR_BUDDY_KEY" > ~/.config/farmland/buddy.key

# 4. (Optional) declare host labels + capabilities, one per line.
#    '#'-comments are fine. Buddy auto-loads these — equivalent to
#    passing '--labels gpu,arm64' / '--capabilities docker,hil'.
$ printf 'gpu\narm64\n' > ~/.config/farmland/labels
$ printf 'docker\n'     > ~/.config/farmland/capabilities

# 5. Start it — no env var, no flag for the key
$ farm-buddy connect --tenant YOUR_TENANT_ID

That's it. The buddy connects, the dashboard's Buddies tab lights up green, and any field that targets the labels this buddy advertises starts dispatching work.

Need to override the default path? Use --key, FARM_BUDDY_API_KEY, or FARM_BUDDY_API_KEY_FILE — the inline --key form leaks plaintext into shell history, so keep it for one-off testing only.

Buddy lifecycle

A buddy can be online, busy (currently building), offline (heartbeat lapsed), or released (admin removed it from the tenant). Only online + busy buddies receive work. The orchestrator re-routes around offline buddies automatically.

Multi-tenant assignment

One buddy can serve multiple fields and even multiple tenants (with admin permission). The dispatch policy is per-field: round-robin, least-loaded, affinity (sticky to recent), or affinity-greedy (sticky if cached, fall back). The dashboard lets you change this per-field without restarting the buddy.

Read more

• Farm Runner — the execution engine Buddy hands off to
• Source on GitHub (farmland-labs)