Install

Five minutes. Local. No cloud. No telemetry.

1. Prerequisites

• Node.js 18+ — node --version should return v18 or higher.
• OpenCode CLI — install from opencode.ai or brew install anomalyco/tap/opencode. Verify with opencode --version.
• A model provider configured — OpenCode needs at least one provider (Anthropic, OpenAI, etc.) to actually run agents. Meshfleet itself doesn't need one.
• macOS, Linux, or Windows (via WSL recommended) — Meshfleet works on all three, but path handling and CLI testing are best on Unix. On Windows, run inside WSL (Windows Subsystem for Linux) for the smoothest experience.

Windows-specific notes

Meshfleet is a Node.js application and runs on Windows natively, but a few things to know:

• Use WSL for the smoothest experience. The install path and CLI have been tested on macOS and Linux. WSL gives you a real Linux environment and matches the dev experience of the other contributors.
• Native Windows path: if you skip WSL, your config goes at %APPDATA%\opencode\opencode.jsonc and the MCP server command should use node from your PATH. The ledger file lands at %APPDATA%\opencode\agent-mesh.json.
• PowerShell install: the install commands in step 2 work in PowerShell. Replace \\ line continuations with ` (backtick) if your shell balks.

2. Clone & build

git clone https://github.com/johnmwhitman/agent-mesh.git \
  ~/.config/opencode/mcp-servers/agent-mesh
cd ~/.config/opencode/mcp-servers/agent-mesh
npm install && npm run build

This downloads the MCP server to ~/.config/opencode/mcp-servers/agent-mesh, installs dependencies, and compiles TypeScript to dist/.

Or install via npm (post-publish)

Once agent-mesh ships to the npm registry (planned for v1.0), the install becomes a single line:

npm install -g agent-mesh

The package bundles a files whitelist of dist/, README.md, LICENSE, and the spec docs (29.3 kB packed, 16 files). prepublishOnly runs build + tests so the published tarball is always green.

Verify the build

npm test
npm run typecheck

You should see 159/159 tests pass and tsc --noEmit exit 0. If either fails, open a GitHub issue with the output.

3. Register the MCP server

Add the following to ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "agent-mesh": {
      "type": "local",
      "enabled": true,
      "command": ["node", "~/.config/opencode/mcp-servers/agent-mesh/dist/index.js"]
    }
  }
}

If you already have an mcp block, just add the agent-mesh entry inside it.

4. Restart OpenCode

Quit and relaunch OpenCode. The Meshfleet MCP tools should appear in your tool list (15 tools in v0.8.4: spawn_fleet, fleet_status, list_fleets, set_fleet_timeout, collect_results, send_message, get_inbox, ack_message, register_capability, route_work, record_routing_outcome, list_agents, attach_agent, subscribe_inbox, get_health, plus the fleet template tools).

5. Spawn your first fleet

From any OpenCode session, call the MCP tools:

const { fleet_id } = await callTool("spawn_fleet", {
  agents: [
    { role: "Explorer", prompt: "Map the auth layer", agent: "codebase-onboarding-engineer" },
    { role: "Analyst",  prompt: "Review the auth architecture", agent: "oracle" },
  ],
});

const { matches } = await callTool("route_work", {
  description: "audit authentication security"
});

You now have a 2-agent fleet. The codebase-onboarding-engineer is one of 100+ premade agent personalities bundled with the project.

Configuration

All optional. The defaults work for most users.

Environment variables

Per-fleet timeout

Override the global timeout for a specific fleet:

await callTool("set_fleet_timeout", { fleet_id: "abc-123", timeout_ms: 60000 })

After this, agents in fleet_id get killed after 60s, while other fleets still use the global default.

Troubleshooting

"MCP server not found" after restart

Verify the path in opencode.jsonc matches the actual install location. Run ls ~/.config/opencode/mcp-servers/agent-mesh/dist/index.js to confirm.

"opencode: command not found" when spawning

Meshfleet spawns opencode run as a child process. Make sure opencode is in your $PATH: which opencode. If it returns a path, you're set.

Agents hang indefinitely

If an agent is stuck (model provider timeout, infinite loop), Meshfleet's per-agent watchdog will kill it after AGENT_MESH_AGENT_TIMEOUT_MS (default 30 min). To force a shorter timeout for testing, set the env var or use set_fleet_timeout per-fleet.

JSON ledger corruption

If agent-mesh.json becomes corrupt (e.g. power loss during write), Meshfleet auto-resets to empty on next load. Inspect the file to recover: cat ~/.config/opencode/agent-mesh.json | jq .. If it's invalid JSON, move it aside and start fresh — no agents in flight will be lost because the MCP server is per-session.

Uninstall

rm -rf ~/.config/opencode/mcp-servers/agent-mesh
rm ~/.config/opencode/agent-mesh.json
rm ~/.config/opencode/agent-mesh.events.log

Then remove the agent-mesh entry from opencode.jsonc. Restart OpenCode.