Connect Agents

connect-agents

Use this when pointing an agent harness or any OpenAI client at a running mesh-llm node. Full reference: docs/AGENTS.md.

Mental model

• Use http://<host>:9337/v1 only for loopback hosts (localhost, 127.0.0.1, or ::1). For non-loopback traffic, use https://<host>:9337/v1, an SSH tunnel that terminates at a loopback endpoint, or trusted private-network isolation; never send cleartext HTTP to an untrusted remote host.
• GET /v1/models lists everything reachable (local + mesh peers); requests route by the model field.
• Special model ids: auto lets the mesh pick; mesh engages the mixture-of-agents path. Otherwise use an exact id from /v1/models.
• For coding agents, pick a tool-capable model. If --model is omitted, the built-in launchers pick the strongest tool-capable model available.

Built-in launchers (preferred)

mesh-llm launches the major agent CLIs with config injected for you:

mesh-llm goose     [--model <id>]                 # writes ~/.config/goose/custom_providers/mesh.json
mesh-llm claude    [--model <id>]
mesh-llm opencode  [--model <id>] [--host <h>]    # injects OPENCODE_CONFIG_CONTENT (no file edits)
mesh-llm pi        [--model <id>] [--host <h>]    # writes ~/.pi/agent/models.json

• goose/claude reuse a local mesh on the chosen --port.
• opencode/pi target --host (default 127.0.0.1:9337) and auto-start a local client only for loopback targets; the auto-started node is cleaned up when the harness exits.
• mesh-llm pi --write / mesh-llm opencode --write update config without launching (use --host for remote meshes).
• Agent launch commands also install available plugin skills for that agent (mesh-llm skills install does it standalone).

Manual config (any OpenAI client)

For a loopback node use http://127.0.0.1:9337/v1; for a remote node use https://<host>:9337/v1, an SSH tunnel, or trusted private-network isolation. Keep the /v1 path and use any non-empty API key:

export GOOSE_PROVIDER=openai GOOSE_MODEL="<id-from-v1-models>"
export OPENAI_HOST="http://127.0.0.1:9337" OPENAI_API_KEY="mesh"

curl -s http://localhost:9337/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'

Exact manual provider JSON for OpenCode and Pi is in docs/AGENTS.md.

Validating agent behavior

Direct API contract probe (tool-call forcing, streaming reconstruction):

scripts/qa-agent-tool-call-reliability.py \
  --base-url http://127.0.0.1:9337/v1 --models auto,mesh --attempts 3 \
  --output target/agent-tool-call-reliability/results.jsonl

Broader harness (models, chat, streaming, plus optional Goose/OpenCode/Pi smokes): scripts/qa-nightly-stability.py — see docs/AGENTS.md. Use --print-plan on either script for a side-effect-free preview.

Blackboard (cross-mesh agent coordination)

Agents can share status/questions across the mesh via the blackboard plugin — even from a client-only node:

mesh-llm plugins install blackboard
mesh-llm blackboard "STATUS: [org/repo branch:main] refactoring billing module"
mesh-llm blackboard --search "QUESTION"

MCP access: the management endpoint http://127.0.0.1:3131/mcp exposes blackboard_post, blackboard_search, blackboard_feed. Posts are visible to every peer — never post secrets, credentials, private paths, or customer data.

Gotchas

• Use a base URL ending in /v1; prefer chat-completions over the Responses API unless the client documents Responses support.
• Model ids must match /v1/models exactly (they can contain spaces — quote them).
• An empty /v1/models usually means the model is still loading or no mesh was joined yet — check /api/status on :3131 (see mesh-join).
• The response "model" field tells you which node/model actually answered.