Getting Started

Run the install script. It downloads two binaries — tailbusd (the daemon) and tailbus (the CLI) — and places them in ~/.local/bin.

Works on Linux (amd64, arm64) and macOS (Apple Silicon, Intel). No dependencies.

Run tailbusd to start the daemon. It will prompt you to log in with Google. Once authenticated, your machine joins the mesh and can discover other nodes on your account.

The daemon runs in the foreground. It opens a Unix socket for local agents and an MCP gateway on port 1423.

The Python SDK talks to the local daemon over a Unix socket. No network config needed — if tailbusd is running, the SDK connects automatically.

An agent is any process that registers a handle and listens for messages. Here's a minimal example — a finance agent that responds to budget queries.

from tailbus import AsyncAgent, Manifest, CommandSpec

agent = AsyncAgent("finance",
  manifest=Manifest(
    description="Budget and spend queries",
    commands=[
      CommandSpec("budget", "Check remaining budget"),
    ],
  )
)

@agent.on_message
async def handle(msg):
  await agent.resolve(
    msg.session,
    "Q3 marketing budget: $48,200 remaining"
  )

await agent.run_forever()

Start your agent. It registers with the daemon and is immediately discoverable by every other agent on your mesh.

Verify it's registered using the CLI:

On the same machine — or any other machine on your mesh — write a second agent that opens a session to finance.

from tailbus import AsyncAgent

agent = AsyncAgent("strategy")

# Open a session to finance — wherever it is
response = await agent.open_session(
  "finance",
  "What's the Q3 marketing budget?"
)

print(response.payload)
# → "Q3 marketing budget: $48,200 remaining"

The daemon resolves the handle, opens a peer-to-peer gRPC connection (with mTLS), and delivers the message. If the agents are on different machines behind NATs, it handles traversal automatically.

The daemon's MCP gateway exposes every registered handle as a tool. Add a single line to your MCP config:

{
  "mcpServers": {
    "tailbus": {
      "url": "http://localhost:1423/mcp"
    }
  }
}

Claude and Cursor now see your agents as tools. If your agent declared commands in its manifest, each command becomes a separate tool:

Agents with commands get tools named handle.command. Agents without commands get a single tool named after their handle.