Agent Discovery

Mesh is the agent discovery and registry system in DorkOS. It scans your filesystem for AI agent projects, registers them with capability manifests, and connects them to Relay for inter-agent communication. For a deeper look at the architecture, see the Mesh concept page.

Enabling Mesh

export DORKOS_MESH_ENABLED=true

dorkos

Discovering Agents

Discovery scans your filesystem for directories that contain recognized agent markers. Mesh ships with strategies for Claude Code (.claude/ directory), Cursor (.cursor/ or .cursorrc), and Codex projects.

Trigger a scan from the UI by opening the Mesh tab and clicking the discover button, or use the REST API:

curl -X POST http://localhost:4242/api/mesh/discover \
  -H "Content-Type: application/json" \
  -d '{ "roots": ["/home/user/projects"], "maxDepth": 3 }'

The response is an array of DiscoveryCandidate objects, each containing the directory path, the strategy that matched, and hints about the agent's name and capabilities. In the UI, each candidate appears as a CandidateCard with accept and deny buttons.

Subsequent scans automatically skip directories that are already registered or denied, and silently re-import agents that have a .dork/agent.json manifest from a previous session.

Agent Manifests

Every registered agent has a manifest that describes its identity and configuration. The manifest is stored both in the Mesh SQLite database and as a .dork/agent.json file in the agent's project directory.

{
  "id": "01HXYZ...",
  "name": "research-agent",
  "description": "Handles web research and summarization tasks",
  "runtime": "claude-code",
  "capabilities": ["web-search", "summarization"],
  "behavior": { "responseMode": "always" },
  "budget": { "maxHopsPerMessage": 5, "maxCallsPerHour": 100 },
  "namespace": "research",
  "registeredAt": "2026-02-26T12:00:00Z",
  "registeredBy": "dorkos-ui"
}

Discovery strategies automatically populate the manifest with hints extracted from the project (name from package.json or directory name, capabilities from detected tooling), but you can override any field during registration.

Registering Agents

There are three ways to register an agent in Mesh.

MeshPanel UI

Open the Mesh tab and click "Register Agent". The RegisterAgentDialog form lets you enter the agent name, capabilities, project path, and optional metadata. You can also accept a discovery candidate directly from the CandidateCard.

REST API

Send a POST request with the agent manifest:

curl -X POST http://localhost:4242/api/mesh/agents \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/home/user/projects/research",
    "overrides": {
      "name": "research-agent",
      "runtime": "claude-code",
      "capabilities": ["web-search", "summarization"]
    }
  }'

MCP Tools

Agents can register other agents (or themselves) using the mesh_register MCP tool:

mesh_register({ path: "/home/user/projects/research", name: "research-agent", runtime: "claude-code", capabilities: ["web-search"] })

When an agent creates a registration via MCP tools, the manifest is written to .dork/agent.json in the project directory and the agent is immediately available in the registry.

Network Topology

The TopologyGraph visualization in the Mesh tab renders your agent network as a hierarchical graph using dagre layout. Agents appear as nodes grouped by namespace, with namespace hub nodes connecting related agents. Cross-namespace edges show permitted communication paths.

Live health data is overlaid on the graph:

• Active nodes — the agent has been seen recently (within the last 5 minutes)
• Inactive nodes — the agent has not been seen for a while but is within 24 hours
• Stale nodes — the agent has not been seen for over 24 hours and may be offline

The MeshStatsHeader above the graph shows aggregate counts: total agents, agents by health state, and agents by runtime type.

Health Monitoring

Mesh tracks agent health through a heartbeat protocol. Agents send periodic heartbeats to signal they are alive and working.

curl -X POST http://localhost:4242/api/mesh/agents/{agentId}/heartbeat \
  -H "Content-Type: application/json" \
  -d '{ "event": "processing-task" }'

When an agent's health state changes (for example, from stale to active after receiving a heartbeat), Mesh emits a lifecycle event through the Relay signal system. The AgentHealthDetail component in the UI provides a per-agent drill-down showing the current state, last seen timestamp, last event, and capabilities.

Access Control

Not every discovered agent should be registered. The denial system lets you exclude directories from future discovery scans.

Denying Agents

Deny a candidate via the UI (click the deny button on a CandidateCard) or the API:

curl -X POST http://localhost:4242/api/mesh/deny \
  -H "Content-Type: application/json" \
  -d '{ "path": "/home/user/projects/legacy-bot", "reason": "Deprecated project" }'

Denied paths are stored in the SQLite database and checked during every scan. The candidate will not appear in future discovery results.

Viewing and Removing Denials

View the denial list and remove entries if you change your mind:

# List denied paths
curl http://localhost:4242/api/mesh/denied

# Remove a denial (re-enables discovery for that path, path is URL-encoded)
curl -X DELETE "http://localhost:4242/api/mesh/denied/%2Fhome%2Fuser%2Fprojects%2Flegacy-bot"

Configuration Reference

Mesh data is stored in the consolidated DorkOS database at ~/.dork/dork.db (managed by Drizzle ORM). Agent manifests are also written to .dork/agent.json in each registered agent's project directory as a portable backup that survives database rebuilds.

Next Steps