[GH-ISSUE #5864] Feature request: AI-agent skills — architecture context, safe composite operations, and impact analysis for agent-driven network management #12186

Open
opened 2026-08-05 01:32:36 -04:00 by saavagebueno · 0 comments
Owner

Originally created by @renne on GitHub (Apr 12, 2026).
Original GitHub issue: https://github.com/netbirdio/netbird/issues/5864

AI agents (GitHub Copilot, Claude, Cursor, etc.) that manage NetBird networks via the REST API or MCP servers consistently cause unexpected side effects and hard-to-diagnose failures. The root cause is not missing API coverage (that is addressed in #5787) — it is that agents have no model of NetBird's architectural planes, cross-plane dependencies, and mutation semantics.

Concrete failures encountered in production

# Failure Root cause
1 DELETE /api/peers/{id} returns HTTP 412 Peer is still referenced as a network router. No warning, no helpful error. Agent had no way to know the dependency existed.
2 PATCH /api/peers/{id} with {"ssh_enabled":true} returns HTTP 500 The endpoint requires a full-object PUT, not PATCH. The community MCP server's update_netbird_peer tool uses PATCH internally, so this failure is systematic.
3 Adding peer to group servers silently opened unexpected access Group servers was the destination of an any → servers: allow all policy. Agent saw only the group membership change; the ACL side effect was invisible without a full policy graph read.
4 Nameserver group created before its peer group existed DNS config is orphaned. No error returned. Agent sequenced operations bottom-up instead of top-down.
5 Re-provisioned peer hostname created docker1-proxy-2, -3, … ghosts Agent did not wipe /var/lib/netbird/ before re-registering. Ghost peers accumulated in group memberships and policies indefinitely.
6 Reverse-proxy service returned 502 for wildcard domain resource Using a wildcard *.docker1 resource as target_id silently breaks host forwarding. Non-wildcard per-hostname resources are required. Agent had no way to know this constraint.
7 Agent tried to configure relay/signal server via management API Relay and signal servers are deployment-level services; they have no public management API. Agent wasted many API calls before failing.

These failures share a common theme: the agent treated NetBird as a flat set of CRUD endpoints and lacked knowledge of:

  • Which architectural plane each resource belongs to
  • How planes connect through the group concept
  • Which operations have side effects across plane boundaries
  • The required ordering of resource creation and deletion

Describe the solution you'd like

1. Architecture reference for AI agents (LLMS.txt + in-repo agent context)

Publish a machine-readable architecture description at https://app.netbird.io/llms.txt (and in the docs / repo under docs/agent-context/) following the llmstxt.org standard. The content must cover all NetBird architectural planes and their interactions:

The planes

Plane Components Key agent misconceptions to correct
Data plane WireGuard tunnels between peers, relay-server (TURN-like, for symmetric NAT), signal-server (WebRTC rendezvous for peer discovery) "Deleting a peer only removes a config entry." — Reality: it immediately tears down all WireGuard tunnels to/from that peer. Services behind it become unreachable.
Routing plane Network resources (IP/CIDR/domain addresses), network routers (peer + metric + masquerade flag), routes (subnet/exit-node/domain), posture checks Agents create resources without assigning a router, or delete a routing peer before removing the resource reference — leaving unreachable resources in the graph.
DNS plane Nameserver groups (domain → upstream DNS server, distributed to peers via groups), DNS zones + records (authoritative internal zones, v0.63+), DNS settings (disabled management groups per account) Agents sequence DNS operations bottom-up; create nameserver groups before referenced peer groups; don't know that NetBird auto-creates a nb.<domain> sub-zone alongside user-created zones.
ACL/Policy plane Groups (peer members + resource members — the universal connector), policies (rules: source groups × destination groups × protocol/ports × direction), posture checks (device compliance gates) Agents modify group membership without understanding that groups simultaneously govern data-plane ACLs, DNS distribution, and routing scope. A single group membership change can open/close access across all three planes at once.
Management plane Management server (REST API + gRPC push to peers), web dashboard, setup keys (enrollment tokens), personal access tokens, users + roles, events log Agents use PATCH (returns 500 for peers); don't know that management pushes config to online peers asynchronously — a config change only takes effect when the peer next connects.
Relay & Signal Relay server (TURN-like relay for NAT traversal, no public management API), signal server (WebRTC signaling, no public management API) Agents attempt to configure relay/signal via management API — these are deployment-level services not exposed in the public API.
Reverse proxy Network resource with target_type: domain, DNS Wildcard Routing setting (off by default), requires ipset on Alpine-based containers Agents use target_type: "peer" (400), use wildcard resources as target_id (502 silent failure), forget to enable DNS Wildcard Routing toggle in Settings.

How planes connect: the Group concept

Groups are the universal connector across all planes. This is the most critical concept for AI agents to internalize:

Peers ──────────────────┐
Network Resources ──────┤ → Group members
                        │
Group ──────────────────┼──→ Policy sources/destinations (ACL plane)
                        ├──→ Route distribution scope (routing plane)
                        ├──→ Nameserver group distribution targets (DNS plane)
                        └──→ Setup key default groups (management plane)

Consequence: any operation that changes group membership (adding/removing a peer or resource) has potential side effects in every other plane. Agents must read the full group graph before modifying membership.

Lifecycle ordering rules

Agents must follow these ordering constraints to avoid 412/400/orphan errors:

Create order (top-down):

  1. Groups (no dependencies)
  2. Peers / network resources (may reference groups)
  3. Policies, routes, nameserver groups (reference groups)
  4. Network routers (reference peers + networks)
  5. DNS zones + records (reference networks)

Delete order (bottom-up):

  1. DNS zone records → DNS zones
  2. Network routers (unlink before deleting the referenced peer)
  3. Routes, policies, nameserver groups
  4. Peers, network resources
  5. Groups (only after all members removed)

2. Dependency graph / impact-analysis API

Before any destructive or structural mutation, agents need to know what depends on a resource. Proposed endpoint:

GET /api/resources/{type}/{id}/dependents

Or as an impact-analysis operation:

POST /api/agent/impact-analysis
Body: {"operation": "delete", "resource_type": "peer", "resource_id": "abc123"}

Example response:

{
  "resource": {"type": "peer", "id": "abc123", "name": "docker1-proxy"},
  "safe_to_proceed": false,
  "blocking_dependencies": [
    {
      "type": "network_router",
      "id": "r1",
      "network_id": "net1",
      "network_name": "docker1-net",
      "required_action": "PUT /api/networks/net1/routers/r1 with peer_id set to null or reassign to another peer"
    }
  ],
  "soft_dependencies": [
    {
      "type": "group",
      "id": "g1",
      "name": "servers",
      "effect": "Removing peer from group will affect 2 policies and 1 nameserver group"
    }
  ]
}

This single endpoint prevents the #1 cause of 412 errors and enables agents to plan safe multi-step deletions automatically.

3. Topology introspection endpoint

AI agents currently need 10+ sequential API calls to build a mental model of a network. A single topology endpoint would replace this:

GET /api/agent/topology

Returns the full network as a labelled graph suitable for AI reasoning:

{
  "peers": [{"id": "...", "name": "...", "groups": [...], "connected": true}],
  "groups": [{"id": "...", "name": "...", "peer_ids": [...], "resource_ids": [...]}],
  "policy_graph": [
    {
      "policy_id": "p1",
      "name": "servers-access",
      "source_groups": ["g-clients"],
      "destination_groups": ["g-servers"],
      "effect": "allow tcp:443,80 bidirectional"
    }
  ],
  "routing_graph": [
    {
      "network_id": "net1",
      "resources": [{"id": "res1", "address": "192.168.1.0/24"}],
      "routers": [{"peer_id": "peer1", "metric": 100, "masquerade": true, "peer_connected": true}]
    }
  ],
  "dns_graph": [
    {
      "nameserver_group_id": "ns1",
      "domains": ["bartschnet.de"],
      "nameservers": ["10.0.0.7:53"],
      "distribution_groups": ["g-all-peers"]
    }
  ]
}

4. Safe composite operations

High-level operations that handle ordering, dependency checks, and cleanup atomically:

Endpoint What it does
DELETE /api/agent/peers/{id}/safe Checks all dependencies, unlinks routers, removes from groups, deletes peer — or returns a structured error if manual intervention is required
POST /api/agent/expose-service Creates network + resource + router + nameserver group + policy in one atomic operation with rollback on failure
POST /api/agent/validate Validates a planned set of API mutations without executing them; returns ordering issues, dependency conflicts, and side effects

5. Official agent skill files

Provide maintained agent skill files in the repository (docs/agent-skills/) that encode safe, plane-aware workflows for popular agent frameworks (GitHub Copilot SKILL.md, Anthropic tool definitions):

Skill Purpose
netbird-architecture.md Explains all planes, components, and cross-plane interactions — the prerequisite for all other skills
netbird-add-peer.md Onboard a peer: enrollment key selection, group assignment, policy check, DNS configuration
netbird-expose-service.md Expose a service end-to-end: network resource + router + policy + DNS (includes reverse-proxy variant and required settings)
netbird-remove-peer.md Safe peer removal: impact analysis → router unlink → group cleanup → delete
netbird-audit-network.md Summarize current topology across all planes; identify orphaned resources, open any-to-any policies, missing routers
netbird-debug-connectivity.md Diagnose why peer A cannot reach resource B: walk the ACL plane → routing plane → DNS plane → data plane

Describe alternatives you've considered

  1. CQ/knowledge-base workaround — Documenting agent gotchas in a local knowledge base (e.g. CQ) per deployment. Works for individual operators but doesn't scale and requires re-discovery per agent session.
  2. Thin MCP wrapper only (#5787) — Exposes raw API as tools but does not prevent agents from calling them in wrong order or without understanding side effects. Necessary but not sufficient.
  3. Agent prompts with inline instructions — Embedding ordering rules in system prompts is fragile, token-expensive, and not version-controlled alongside the API.

Additional context

  • This request is complementary to #5787 (official MCP server). #5787 provides the tools; this request provides the intelligence and safety guardrails that make those tools usable without side effects.
  • Related: #5810 (expose peer LAN IPs) — the topology endpoint proposed here would benefit from that data.
  • The llmstxt.org standard is already adopted by many developer tools (Vercel, Stripe, etc.) as the canonical way to provide AI-agent context.
  • NetBird's architectural complexity (7 planes, groups as universal connector, ordering constraints) is unusually high for a management API. Without explicit agent guidance, incorrect usage is the expected default — not the exception.
Originally created by @renne on GitHub (Apr 12, 2026). Original GitHub issue: https://github.com/netbirdio/netbird/issues/5864 ## Is your feature request related to a problem? Please describe. AI agents (GitHub Copilot, Claude, Cursor, etc.) that manage NetBird networks via the REST API or MCP servers consistently cause **unexpected side effects and hard-to-diagnose failures**. The root cause is not missing API coverage (that is addressed in #5787) — it is that agents have no model of NetBird's **architectural planes, cross-plane dependencies, and mutation semantics**. ### Concrete failures encountered in production | # | Failure | Root cause | |---|---|---| | 1 | `DELETE /api/peers/{id}` returns HTTP 412 | Peer is still referenced as a network router. No warning, no helpful error. Agent had no way to know the dependency existed. | | 2 | `PATCH /api/peers/{id}` with `{"ssh_enabled":true}` returns HTTP 500 | The endpoint requires a full-object `PUT`, not `PATCH`. The community MCP server's `update_netbird_peer` tool uses `PATCH` internally, so this failure is systematic. | | 3 | Adding peer to group `servers` silently opened unexpected access | Group `servers` was the destination of an `any → servers: allow all` policy. Agent saw only the group membership change; the ACL side effect was invisible without a full policy graph read. | | 4 | Nameserver group created before its peer group existed | DNS config is orphaned. No error returned. Agent sequenced operations bottom-up instead of top-down. | | 5 | Re-provisioned peer hostname created `docker1-proxy-2`, `-3`, … ghosts | Agent did not wipe `/var/lib/netbird/` before re-registering. Ghost peers accumulated in group memberships and policies indefinitely. | | 6 | Reverse-proxy service returned 502 for wildcard domain resource | Using a wildcard `*.docker1` resource as `target_id` silently breaks `host` forwarding. Non-wildcard per-hostname resources are required. Agent had no way to know this constraint. | | 7 | Agent tried to configure relay/signal server via management API | Relay and signal servers are deployment-level services; they have no public management API. Agent wasted many API calls before failing. | These failures share a common theme: the agent treated NetBird as a flat set of CRUD endpoints and lacked knowledge of: - Which architectural **plane** each resource belongs to - How planes **connect** through the group concept - Which operations have **side effects** across plane boundaries - The required **ordering** of resource creation and deletion --- ## Describe the solution you'd like ### 1. Architecture reference for AI agents (LLMS.txt + in-repo agent context) Publish a machine-readable architecture description at `https://app.netbird.io/llms.txt` (and in the docs / repo under `docs/agent-context/`) following the [llmstxt.org](https://llmstxt.org) standard. The content must cover all NetBird architectural **planes** and their interactions: #### The planes | Plane | Components | Key agent misconceptions to correct | |---|---|---| | **Data plane** | WireGuard tunnels between peers, relay-server (TURN-like, for symmetric NAT), signal-server (WebRTC rendezvous for peer discovery) | "Deleting a peer only removes a config entry." — Reality: it immediately tears down all WireGuard tunnels to/from that peer. Services behind it become unreachable. | | **Routing plane** | Network resources (IP/CIDR/domain addresses), network routers (peer + metric + masquerade flag), routes (subnet/exit-node/domain), posture checks | Agents create resources without assigning a router, or delete a routing peer before removing the resource reference — leaving unreachable resources in the graph. | | **DNS plane** | Nameserver groups (domain → upstream DNS server, distributed to peers via groups), DNS zones + records (authoritative internal zones, v0.63+), DNS settings (disabled management groups per account) | Agents sequence DNS operations bottom-up; create nameserver groups before referenced peer groups; don't know that NetBird auto-creates a `nb.<domain>` sub-zone alongside user-created zones. | | **ACL/Policy plane** | Groups (peer members + resource members — the universal connector), policies (rules: source groups × destination groups × protocol/ports × direction), posture checks (device compliance gates) | Agents modify group membership without understanding that groups simultaneously govern data-plane ACLs, DNS distribution, and routing scope. A single group membership change can open/close access across all three planes at once. | | **Management plane** | Management server (REST API + gRPC push to peers), web dashboard, setup keys (enrollment tokens), personal access tokens, users + roles, events log | Agents use `PATCH` (returns 500 for peers); don't know that management pushes config to online peers asynchronously — a config change only takes effect when the peer next connects. | | **Relay & Signal** | Relay server (TURN-like relay for NAT traversal, no public management API), signal server (WebRTC signaling, no public management API) | Agents attempt to configure relay/signal via management API — these are deployment-level services not exposed in the public API. | | **Reverse proxy** | Network resource with `target_type: domain`, DNS Wildcard Routing setting (off by default), requires `ipset` on Alpine-based containers | Agents use `target_type: "peer"` (400), use wildcard resources as `target_id` (502 silent failure), forget to enable DNS Wildcard Routing toggle in Settings. | #### How planes connect: the Group concept **Groups are the universal connector across all planes.** This is the most critical concept for AI agents to internalize: ``` Peers ──────────────────┐ Network Resources ──────┤ → Group members │ Group ──────────────────┼──→ Policy sources/destinations (ACL plane) ├──→ Route distribution scope (routing plane) ├──→ Nameserver group distribution targets (DNS plane) └──→ Setup key default groups (management plane) ``` **Consequence:** any operation that changes group membership (adding/removing a peer or resource) has potential side effects in every other plane. Agents must read the full group graph before modifying membership. #### Lifecycle ordering rules Agents must follow these ordering constraints to avoid 412/400/orphan errors: **Create order (top-down):** 1. Groups (no dependencies) 2. Peers / network resources (may reference groups) 3. Policies, routes, nameserver groups (reference groups) 4. Network routers (reference peers + networks) 5. DNS zones + records (reference networks) **Delete order (bottom-up):** 1. DNS zone records → DNS zones 2. Network routers (unlink before deleting the referenced peer) 3. Routes, policies, nameserver groups 4. Peers, network resources 5. Groups (only after all members removed) ### 2. Dependency graph / impact-analysis API Before any destructive or structural mutation, agents need to know what depends on a resource. Proposed endpoint: ``` GET /api/resources/{type}/{id}/dependents ``` Or as an impact-analysis operation: ``` POST /api/agent/impact-analysis Body: {"operation": "delete", "resource_type": "peer", "resource_id": "abc123"} ``` **Example response:** ```json { "resource": {"type": "peer", "id": "abc123", "name": "docker1-proxy"}, "safe_to_proceed": false, "blocking_dependencies": [ { "type": "network_router", "id": "r1", "network_id": "net1", "network_name": "docker1-net", "required_action": "PUT /api/networks/net1/routers/r1 with peer_id set to null or reassign to another peer" } ], "soft_dependencies": [ { "type": "group", "id": "g1", "name": "servers", "effect": "Removing peer from group will affect 2 policies and 1 nameserver group" } ] } ``` This single endpoint prevents the #1 cause of 412 errors and enables agents to plan safe multi-step deletions automatically. ### 3. Topology introspection endpoint AI agents currently need 10+ sequential API calls to build a mental model of a network. A single topology endpoint would replace this: ``` GET /api/agent/topology ``` Returns the full network as a **labelled graph** suitable for AI reasoning: ```json { "peers": [{"id": "...", "name": "...", "groups": [...], "connected": true}], "groups": [{"id": "...", "name": "...", "peer_ids": [...], "resource_ids": [...]}], "policy_graph": [ { "policy_id": "p1", "name": "servers-access", "source_groups": ["g-clients"], "destination_groups": ["g-servers"], "effect": "allow tcp:443,80 bidirectional" } ], "routing_graph": [ { "network_id": "net1", "resources": [{"id": "res1", "address": "192.168.1.0/24"}], "routers": [{"peer_id": "peer1", "metric": 100, "masquerade": true, "peer_connected": true}] } ], "dns_graph": [ { "nameserver_group_id": "ns1", "domains": ["bartschnet.de"], "nameservers": ["10.0.0.7:53"], "distribution_groups": ["g-all-peers"] } ] } ``` ### 4. Safe composite operations High-level operations that handle ordering, dependency checks, and cleanup atomically: | Endpoint | What it does | |---|---| | `DELETE /api/agent/peers/{id}/safe` | Checks all dependencies, unlinks routers, removes from groups, deletes peer — or returns a structured error if manual intervention is required | | `POST /api/agent/expose-service` | Creates network + resource + router + nameserver group + policy in one atomic operation with rollback on failure | | `POST /api/agent/validate` | Validates a planned set of API mutations without executing them; returns ordering issues, dependency conflicts, and side effects | ### 5. Official agent skill files Provide **maintained agent skill files** in the repository (`docs/agent-skills/`) that encode safe, plane-aware workflows for popular agent frameworks (GitHub Copilot `SKILL.md`, Anthropic tool definitions): | Skill | Purpose | |---|---| | `netbird-architecture.md` | Explains all planes, components, and cross-plane interactions — the prerequisite for all other skills | | `netbird-add-peer.md` | Onboard a peer: enrollment key selection, group assignment, policy check, DNS configuration | | `netbird-expose-service.md` | Expose a service end-to-end: network resource + router + policy + DNS (includes reverse-proxy variant and required settings) | | `netbird-remove-peer.md` | Safe peer removal: impact analysis → router unlink → group cleanup → delete | | `netbird-audit-network.md` | Summarize current topology across all planes; identify orphaned resources, open any-to-any policies, missing routers | | `netbird-debug-connectivity.md` | Diagnose why peer A cannot reach resource B: walk the ACL plane → routing plane → DNS plane → data plane | --- ## Describe alternatives you've considered 1. **CQ/knowledge-base workaround** — Documenting agent gotchas in a local knowledge base (e.g. CQ) per deployment. Works for individual operators but doesn't scale and requires re-discovery per agent session. 2. **Thin MCP wrapper only (#5787)** — Exposes raw API as tools but does not prevent agents from calling them in wrong order or without understanding side effects. Necessary but not sufficient. 3. **Agent prompts with inline instructions** — Embedding ordering rules in system prompts is fragile, token-expensive, and not version-controlled alongside the API. --- ## Additional context - This request is **complementary** to #5787 (official MCP server). #5787 provides the *tools*; this request provides the *intelligence and safety guardrails* that make those tools usable without side effects. - Related: #5810 (expose peer LAN IPs) — the topology endpoint proposed here would benefit from that data. - The [llmstxt.org](https://llmstxt.org) standard is already adopted by many developer tools (Vercel, Stripe, etc.) as the canonical way to provide AI-agent context. - NetBird's architectural complexity (7 planes, groups as universal connector, ordering constraints) is unusually high for a management API. Without explicit agent guidance, incorrect usage is the expected default — not the exception.
Sign in to join this conversation.
No Label
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: DYNR/netbird#12186