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. Mesh is always on — no feature flag or environment variable required. For a deeper look at the architecture, see the Mesh concept page.

Two registries: installed vs discovered

DorkOS maintains two independent agent registries, populated by two different scanners, backing two different APIs. They answer different questions and shouldn't be conflated:

When to use which

• "What agents did I install from the marketplace?" → installed-scanner / GET /api/marketplace/installed. This answers a narrow provenance question — packages that came through the managed marketplace pipeline with their .dork/install-metadata.json sidecar intact.
• "What agents does my system know about right now?" → mesh registry / GET /api/agents. This is the full fleet — every directory with a .dork/agent.json manifest that Mesh has been pointed at, whether via the marketplace install pipeline, manual registration, or a discovery scan.

Marketplace installs always land under ~/.dork/{plugins,agents}/ with provenance metadata, so they also show up in the mesh registry after the install hands off. Mesh-discovered agents do not necessarily appear in the installed-scanner's results — if an agent was registered from a directory the marketplace never touched, there is no install-metadata sidecar and the installed-scanner ignores it.

Where agents can live

Any directory with a .dork/agent.json file is a valid agent location. You are not restricted to ~/.dork/agents/. Common patterns:

• Marketplace installs → ~/.dork/agents/<name>/.dork/agent.json (managed by the install pipeline)
• Project-local agents → <your-project>/.dork/agent.json (useful when an agent is version-controlled alongside the code it maintains)
• Arbitrary locations → any absolute path in mesh.scanRoots in ~/.dork/config.json, or passed explicitly to mesh_discover

Discovery is pull-based

Mesh does not watch your filesystem for new .dork/agent.json files. Discovery runs when you trigger it:

• Clicking "Scan for Agents" in the UI
• Calling POST /api/mesh/discover or the mesh_discover MCP tool
• On startup, the background reconciler walks every path in mesh.scanRoots (configured in config.json) and picks up any new manifests since the last scan

If you drop a new .dork/agent.json file into a directory Mesh has never walked, it is invisible until a scan hits that directory. This is intentional — filesystem watchers are expensive and noisy, and pull-based discovery gives you deterministic control over when the registry changes.

Manifest write-through semantics (the file-on-disk is authoritative, the SQLite registry is a derived cache) are covered by the agent-storage contributor rule and ADR-0043.

Discovering Agents

Discovery scans your filesystem for directories that contain recognized agent markers. Mesh ships with ten detection strategies covering the major AI coding agents:

The AgentRuntime enum also includes placeholder values for agents that do not yet have detection strategies: augment, jetbrains-ai, kilo-code, trae, and other.

In addition, any directory that already contains a .dork/agent.json manifest is auto-imported — the agent is silently added to the registry without requiring your approval again.

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": 5 }'

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 approve 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 discover and register other agents using the mesh MCP tools.

Scan for candidates:

mesh_discover({ roots: ["/home/user/projects"], maxDepth: 5 })

By default this returns only unregistered candidates. Pass includeRegistered: true to also see agents that were auto-imported during the scan (directories with an existing .dork/agent.json):

mesh_discover({ roots: ["/home/user/projects"], includeRegistered: true })

Register an agent directly:

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, Mesh emits a lifecycle event through the Relay signal system. The AgentHealthDetail component 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