Mesh

Mesh is the agent discovery and registry system in DorkOS. It scans your filesystem for AI agent projects, registers them into a central registry, and connects them to Relay so they can communicate. Mesh is always on — no environment variable required.

What Mesh Does

When you're running agents across multiple projects, they are invisible to each other by default. A Claude Code agent working on your backend has no awareness of the Cursor agent editing your frontend. You become the router — manually copying context between sessions.

Mesh solves this. It scans your filesystem for agent-capable project directories, builds a registry of known agents, and wires them into Relay so they can reach each other. Discovery is intentional: Mesh finds candidates and presents them for your approval before anything is registered.

Discovery

Discovery scans directories to find agent projects. Mesh uses pluggable detection strategies to recognize different agent types by their filesystem markers.

Built-in Strategies

DorkOS 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 by the scanner — the agent is silently added to the registry without appearing as a candidate. This is scanner behavior, not a detection strategy.

Each strategy checks whether a directory matches its markers and gathers information about the agent — suggested name, runtime type, inferred capabilities, and description.

Scan Process

When you trigger a discovery scan, Mesh walks the specified root directories up to a configurable depth (default: 5 levels). For each directory, it runs every strategy's detection logic. Several behaviors happen automatically:

• Auto-import — If a directory already has a .dork/agent.json manifest, the agent is silently imported into the registry without appearing as a candidate. Re-scanning picks up previously registered agents without requiring you to approve them again.
• Skip registered — Directories already in the registry are skipped entirely.
• Skip denied — Directories you have explicitly denied are also skipped.

The scan yields DiscoveryCandidate objects for directories that match a strategy but are not yet registered or denied.

Registration

When you approve a candidate, Mesh registers it as a full agent:

1. ID generation — A ULID is assigned, providing a unique, time-ordered identifier.
2. Manifest creation — An AgentManifest is assembled from discovery hints merged with any overrides you provide.
3. Manifest persistence — A .dork/agent.json file is written to the agent's project directory. This file survives re-scans and can be committed to version control.
4. Registry insertion — The agent is inserted into the SQLite-backed registry with its manifest, project path, namespace, and scan root.
5. Relay endpoint — If Relay is enabled, a Relay endpoint is automatically registered for the agent, enabling it to receive messages from other agents.

You can also register an agent directly by project path without running a discovery scan, which is useful when you know exactly which directory to target.

The Agent Manifest

Every registered agent has a manifest stored in .dork/agent.json:

Namespaces

Mesh groups agents into namespaces derived from their filesystem location — the project path relative to the scan root. An agent at /home/user/projects/backend/api-service with scan root /home/user/projects gets namespace backend.

Namespaces serve two purposes:

• Topology grouping — The UI groups agents by namespace in the topology view.
• Access control — Agents within the same namespace can communicate freely through Relay. Cross-namespace communication requires explicit allow rules.

Cross-Namespace Access

By default, agents in different namespaces cannot message each other. You add cross-namespace allow rules to open specific paths. Rules are unidirectional — allowing A to message B does not automatically allow B to message A.

Under the hood, Mesh writes Relay access control rules with a priority scheme:

Denial List

The denial list lets you permanently skip specific directories so they do not appear as candidates in future scans. Denials persist in the database and are checked during every scan. You can remove a denial later to allow the directory to appear as a candidate again.

Topology

The topology view provides a namespace-scoped picture of the agent network. It returns:

• Namespaces — Each namespace with its agent count and member agents
• Access rules — The cross-namespace allow/deny rules governing inter-namespace communication

The view respects access rules as boundaries. An agent in namespace A only sees agents in namespaces it can communicate with — agents cannot discover the existence of agents they are not permitted to contact.

Health and Observability

Mesh tracks every agent through a heartbeat mechanism. Each agent has a lastSeenAt timestamp and a lastSeenEvent description updated whenever it sends a heartbeat or performs an action.

Health states:

• active — Seen recently
• inactive — Not seen for a while but within a reasonable window
• stale — Not seen for an extended period, may be offline

When an agent's health status changes, Mesh emits a lifecycle event through Relay's signal system. The DorkOS UI subscribes to these events to update the topology graph in real time.

The aggregate mesh status gives a bird's-eye view: total agent count with breakdowns by health status, agents grouped by runtime, and agents grouped by project directory.

Storage

Mesh stores its data in ~/.dork/dork.db, managed by Drizzle ORM:

• Agent registry (agents table) — All registered agents with manifests, project paths, namespaces, and health fields
• Denial list (agent_denials table) — Paths explicitly excluded from discovery
• Rate limiting (rate_limit_buckets table) — Sliding-window rate limits per agent

Each registered agent also has a .dork/agent.json file in its project directory. This file is the portable representation of the manifest — it survives database rebuilds and allows agents to be re-imported via auto-import during future scans.

Relay Integration

When both Mesh and Relay are enabled, registering an agent in Mesh automatically creates a Relay endpoint for it at relay.agent.{namespace}.{agentId}. This means:

• Registration creates a Relay endpoint and sets up intra-namespace access rules so agents in the same namespace can communicate immediately.
• Unregistration cleans up the Relay endpoint. If it was the last agent in its namespace, the namespace-specific access rules are removed too.
• Lifecycle signals broadcast health status changes on the mesh.agent.lifecycle.* subject pattern.

Once registered, an agent is immediately reachable through Relay with no additional configuration.

Next Steps