Distributed Companions

Multi-agent coordination with specialized roles and cross-cluster communication.

The Problem

Kubernetes is great for orchestrating containers, but not everything runs in Kubernetes. Your NAS sits on a shelf. Your Raspberry Pi monitors a 3D printer. A build server runs bare metal in a closet. An AI agent that only operates inside its own cluster is blind to the rest of your infrastructure. You need a way to extend the agent's reach to any machine, without requiring Kubernetes on every node.

How Baker Street Solves It

Companions are lightweight agent daemons that run on machines outside the Kubernetes cluster. Each companion connects to NATS, announces its capabilities, and receives tasks from the Brain. They are the agent's hands and eyes in the physical world.

A companion on your NAS might expose filesystem browsing, ZFS pool status, and snapshot management. A companion on a build server might offer Docker image builds and CI pipeline triggers. A companion on a Raspberry Pi might provide GPIO sensor readings and device control.

The protocol is simple: the companion registers its available tools over NATS, the Brain discovers them just like extension pods, and Claude can dispatch tasks to any companion. Results flow back through NATS with the same status reporting used by workers.

Companions are designed to be minimal. They do not need Claude, a web server, or any heavy dependencies. The daemon connects to NATS, advertises tools, runs commands, and reports back. You can write one in any language that has a NATS client.

Example

// Companion running on a NAS
import { createCompanion } from "@bakerst/companion-sdk";

const companion = createCompanion({
  name: "nas-helios",
  location: "Home office NAS",
  natsUrl: "nats://nats.baker-street:4222",
});

companion.addTool({
  name: "zfs_status",
  description: "Get ZFS pool health and capacity",
  handler: async () => {
    const output = await runCommand("zpool", ["status", "-v"]);
    return { raw: output, healthy: !output.includes("DEGRADED") };
  },
});

companion.addTool({
  name: "list_shares",
  description: "List available SMB/NFS shares",
  handler: async () => {
    const smb = await runCommand("smbstatus", ["--shares"]);
    const nfs = await runCommand("showmount", ["-e", "localhost"]);
    return { smb, nfs };
  },
});

companion.start();

Learn More

See the Companions documentation for the companion SDK reference, deployment guides for common platforms, and the NATS registration protocol.