# Agent Link

One message bus between my Mac, the Fedora laptop on my monitor and every coding agent on both. Agents talk over MCP, scripts over a small HTTP API, and I work it from a CLI — all reading and writing the same queue. Messages store and forward, so an agent can hand work to a sleeping laptop and it is still there when the lid opens. A read-only task board turns every task-kind message into open and acknowledged work, in the browser and over MCP.

**Status:** Live · Agents · 2026

- **Local checkout:** `/Users/simon/Developer/agent-link` (branch `main`, last commit f4a2ec8, 2026-10-27 — docs: drop the unused cover render)
- **Uncommitted changes:** 12 file(s) at brief generation time
- **Repository:** https://github.com/ShimonNavon/agent-link
- **On another machine:** `git clone https://github.com/ShimonNavon/agent-link` — the paths below are Simon's Mac
- **Live:** http://ubuntu03:30110/
- **How it works:** https://projects.navonsimon.com/agent-link.html
- **Task board:** http://ubuntu03:30124/
- **Where it runs:** namespace agent-link · hub NodePort 30110 · board NodePort 30124 · tailnet only
- **Note:** Bus + task board on my tailnet

## Stack

Python stdlib, MCP Streamable HTTP, SQLite, Kubernetes, Tailscale, Task board

## Start here

- `hub.py` — the whole service: HTTP API (/v1/*), MCP (/mcp and /mcp/<agent-id>), status page, /install.sh and /link.py
- `link.py` — the CLI (send, inbox, agents, read, watch, status) and the stdio MCP bridge (agent-link mcp)
- `board.py, board.html` — read-only task board service: /api/board, /api/task/<id>, MCP (board_tasks, board_agents, board_summary, board_task) and the 1920-ready dashboard page
- `install.sh` — served at /install.sh; installs the CLI into ~/.local/bin and registers an identity
- `deploy/deploy.sh, deploy/k8s.yaml` — namespace agent-link, NodePort 30110, PVC data, ConfigMap hub-code
- `tests/test_link.py` — hub, MCP and CLI smoke tests against a real hub process

## Commands

- **Run locally:** `PORT=18080 AGENT_LINK_DB=/tmp/link.db PUBLIC_URL=http://127.0.0.1:18080 python3 hub.py`
- **Focused tests:** `python3 tests/test_link.py`
- **Publish:** `./deploy/deploy.sh`
- **Connect a machine:** `curl -fsSL http://ubuntu03:30110/install.sh | sh -s -- --id <machine>-<agent> --name '<label>'`
- **Send from a shell:** `agent-link send mac-hermes 'rerun the ledger build' -k task -s ledger`
- **Run the board locally:** `PORT=18081 AGENT_LINK_DB=/tmp/link.db STATIC_DIR=. PUBLIC_URL=http://127.0.0.1:18081 python3 board.py`
- **Board MCP through the registry:** `curl -s -X POST http://ubuntu03:30105/mcp -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"agent-board__board_summary","arguments":{}}}'`

## Deploy and where it runs

- Namespace agent-link, Deployment hub (python:3.13-alpine, code from ConfigMap hub-code), NodePort 30110 at http://ubuntu03:30110/.
- Messages live in SQLite on a local-path PVC (1Gi) at /data, so a rollout keeps the queue; strategy Recreate avoids RWO contention.
- The hub is also proxied by the tailnet MCP registry as the 'agent-link' server, so an agent that only knows the registry still gets the tools (pass from/as there).
- CI: .github/workflows/ci.yml runs tests/test_link.py on Python 3.11 and 3.13.
- Board Deployment (python:3.13-alpine, code from ConfigMap board-code) mounts the queue PVC read-only and serves NodePort 30124 at http://ubuntu03:30124/; MCP at /mcp, proxied by the registry as agent-board.

## Current state

Live since 2026-10-27. Connected: mac-opencode, mac-hermes, mac-claude, mac-codex, mac-simon, fedora-opencode, fedora-simon. The Fedora laptop is tailnet host 'home' (100.82.194.118). The task board is live at http://ubuntu03:30124/ (board MCP registered as agent-board); it reads the same queue and never writes.

## Watch out

- Identity comes from the MCP URL (/mcp/<agent-id>). Through the registry gateway, pass from/as in the tool arguments instead.
- In-cluster clients must use http://hub.agent-link.svc.cluster.local/mcp; ubuntu03 is not resolvable from a pod.
- The hub's Host allowlist rejects unknown hostnames: add a new name to ALLOWED_HOSTS before using it.
- Messages are plain text in SQLite in the pod's PVC; never put secrets in them.
- stdout must stay clean in hub.py: nothing but the HTTP service may print, or JSON-RPC tool pipes break.
- The board opens SQLite read-only (file:...?mode=ro) while the hub writes in WAL mode; do not point it at a non-existent DB, /healthz then returns 503. The board must never write: sends and acks stay with hub.py.

## Secrets — locations only, never print values

- None required. AGENT_LINK_TOKEN is an optional shared bearer token (hub env + client config/env).
- CLI config: ~/.config/agent-link/config.json on the Mac and on Fedora.

## Tags

MCP, HTTP API, CLI, Tailscale, Kubernetes, Task board

---

Brief generated 2026-11-08 from `~/Developer/my-projects/context/`. Canonical URL: https://projects.navonsimon.com/context/agent-link.md
