DOCSEARCHbyAlgolia
Submit Docs

NetBird

repository·main·Indexed 12 days ago

https://github.com/netbirdio/netbird

A zero-config, peer-to-peer private network platform combining a WireGuard-based overlay network with a centralized access control system. It features an Agent Network for AI agents to provide identity-based access to LLM APIs and internal resources, including spending limits, model restrictions, and usage attribution via an identity-aware reverse proxy.

Tokens
70.1K
Snippets
207
Records
345
Agent score
98%

What's inside NetBird

  1. Overview of Agent Networks

    main

    Agent Networks is an LLM-aware reverse-proxy middleware system designed to provide observability and control over LLM requests. It uses a middleware chain synthesized by the management server and executed by the proxy on every request.

    Key capabilities include:

    • Account-level controls: Budget rules, log collection toggles, and PII redaction.
    • Middleware execution: Enforces quotas, injects identity, redacts PII, parses tokens/cost, and emits access logs.
    • Observability: A single AI Observability dashboard page with four tabs for monitoring.

    Core Components:

    • Backend: Primarily located in management/server/agentnetwork, proxy/internal/middleware, and proxy/internal/llm. Wire contracts are in shared/management.
    • Dashboard: Located in the dashboard repository under src/modules/agent-network/ and src/app/(dashboard)/agent-network/.

  2. Overview of Agent Networks architecture

    main

    Agent Networks is an LLM-aware reverse-proxy middleware system integrated with account-level controls. It allows for managing LLM interactions through a synthesized middleware chain that is executed on every request.

    Key capabilities include:

    • Budget Rules: Controlling LLM usage costs.
    • Log Collection Toggles: Managing observability.
    • PII Redaction: Protecting sensitive information.

    The management server synthesizes a per-peer middleware chain, which the proxy then executes for every LLM request.

  3. What is NetBird Agent Network

    main

    NetBird Agent Network is an access control layer designed for AI agents. It provides every agent with a real identity tied to an Identity Provider (IdP) and governs access to LLM APIs, AI gateways, and internal resources.

    Key capabilities include:

    • Identity-based access: Traffic flows over an encrypted NetBird tunnel scoped by policy, eliminating the need to distribute API keys to agents.
    • Spending and rate limits: Set hard caps on costs and request rates per agent, user, or team.
    • Model restriction: Restrict agents to specific approved models and providers.
    • Usage attribution: Track token consumption and costs by identity, group, or cost center.
    • AI Gateway integration: You can point the NetBird proxy at an existing AI gateway to add identity and governance without changing your gateway's routing configuration.

  4. What is the NetBird Signal Server?

    main
    The NetBird Signal Server is a signal-exchange server and client library designed to facilitate the exchange of connection information between NetBird peers. It acts as a signaling mechanism to help peers establish connectivity.

  5. Understand the limitations of the Proxy Middleware Framework

    main

    When building or integrating middlewares within the NetBird proxy framework, be aware of the following architectural constraints and non-goals:

    • Communication: There is no middleware-to-middleware RPC. The only way for middlewares to communicate is via the shared metadata bag.
    • Body Inspection: The framework does not support streaming body inspection. Middlewares only see a bounded prefix of the body. For SSE or chunked parsing, the response middleware operates against that prefix.
    • Ordering: There is no per-spec priority mechanism. The execution order is strictly determined by the registration order in the spec slice.
    • Error Handling: The framework does not implement retry or circuit-breaker logic for middleware errors. The fail-mode is binary (open or closed) and is applied per-spec.
    • Mutation Constraints: Middlewares cannot rewrite the request URL path or query parameters. Only the RewriteUpstream mechanism can change the scheme or host (and optionally perform path replacement).
    • Security/Redaction: Redaction is a best-effort feature and should not be relied upon as a Data Loss Prevention (DLP) solution.

  6. Use the SSE Scanner for streaming LLM responses

    main

    The Scanner is a bufio-backed utility used to parse Server-Sent Events (SSE) from LLM providers.

    Constraints and Safety:

    • Memory Protection: It uses a 64 KiB read buffer and a 1 MiB maximum line length to prevent malicious upstream responses from exhausting process memory.
    • Concurrency: The scanner is not safe for concurrent use. Every consumer must create a fresh scanner instance per response body.
    • Partial Data: The scanner is designed to handle partial chunks; a buffered prefix that does not end in \n\n will still yield its accumulated event before io.EOF is reached.
    • Error Handling: Streaming accumulators (like accumulateOpenAIStream) will break on any scanner error and return partial usage data rather than aborting the entire request.

  7. Control Access Log collection via EnableLogCollection

    main

    Access log emission is gated by the EnableLogCollection setting in the agent network settings.

    • When EnableLogCollection is false: The accesslog middleware suppresses the actual log writing (l.log), but it does not stop trackUsage. This ensures that bandwidth telemetry and usage tracking remain accurate even when detailed access logs are disabled.
    • The suppression is propagated from agentnetwork.Settings.EnableLogCollection through the PathTarget.DisableAccessLog field to the ReverseProxy request context.

  8. Understand the shared/api wire contracts

    main

    The shared/api module defines the cross-process communication contracts between the management server, the proxy, and the dashboard/CLI. It ensures that different components of the NetBird ecosystem can communicate using consistent data formats.

    There are two primary communication interfaces:

    1. gRPC (Management ↔ Proxy): Defined in shared/management/proto/proxy_service.proto. This is used for high-performance, low-latency communication between the management server and the proxy.
    2. REST (Dashboard/CLI ↔ Management): Defined in shared/management/http/api/openapi.yml. This is the standard interface for the web UI and command-line tools to interact with the management server.

    Note: All generated code (e.g., proxy_service.pb.go, types.gen.go) must be kept in sync with these source files to prevent communication errors.

  9. Understand NetBird Daemon Status values

    main

    The NetBird client UI uses specific status strings to represent the state of the tunnel and the daemon. Note that DaemonUnavailable is a synthetic value used by the UI when the gRPC socket is unreachable and does not exist in the actual daemon enum.

    ValueMeaning
    "Idle"Tunnel down (Up never invoked or Down completed)
    "Connecting"Up in progress
    "Connected"Tunnel up
    "NeedsLogin"Fresh install or token cleared; needs Login → SSO → Up
    "LoginFailed"Previous Login attempt errored
    "SessionExpired"SSO token expired; needs re-Login
    "DaemonUnavailable"Synthetic — UI side, emitted when the daemon gRPC socket is unreachable.

  10. Systemd-networkd integration on Linux

    main

    On Linux systems using systemd-networkd, NetBird creates a drop-in configuration file at /etc/systemd/networkd.conf.d/99-netbird.conf.

    This configuration prevents systemd-networkd from removing routes and policy rules that are managed by NetBird by setting:

    • ManageForeignRoutes=no
    • ManageForeignRoutingPolicyRules=no

    This configuration is automatically created during install or reconfigure and removed during uninstall.

  11. Request lifecycle through the LLM middleware chain (Flow B)

    main

    When an agent sends an LLM request (e.g., OpenAI/Anthropic POST /v1/chat/completions) through the netbird-proxy, it passes through a synthesized middleware chain. The order of these middlewares is critical for maintaining security and accounting invariants.

    The Middleware Chain Sequence

    1. Auth: Identifies the peer (user, groups).
    2. Service Mapping: Resolves the service from the Host and path.
    3. LLM Request Parser: Parses the body for provider, model, prompt, and token estimates.
      • capture_prompt controls whether the raw prompt is emitted (nil = legacy, false = drop, true = emit).
    4. LLM Router: Routes the request to an upstream candidate.
    5. LLM Limit Check: Calls the Management server via CheckLLMPolicyLimits.
      • If Denied: Emits an access-log (if EnableLogCollection is ON) and returns 429 or 403 based on the deny_code.
      • If Allowed: Continues to the next step.
    6. LLM Identity Inject: Injects NetBird identity headers per provider configuration.
    7. LLM Guardrail: Enforces a per-provider allowlist (a fail-closed backstop) and performs PII redaction (e.g., phones, emails, credit cards) if settings.RedactPii is enabled.
    8. Upstream LLM: Forwards the request over WireGuard.
    9. LLM Response Parser: Parses the response (JSON or SSE stream).
      • capture_completion controls whether the raw completion is captured.
    10. Cost Meter: Computes cost using pricing.yaml based on usage tokens.
    11. LLM Limit Record: Calls the Management server via RecordLLMUsage to report tokens, cost, groups, and user. This must follow llm_limit_check to ensure successful checks are recorded.
    12. Access Log: Emits an entry if settings.EnableLogCollection is ON.

    Important Invariants

    • Fail-Open Trade-off: The llm_guardrail acts as a per-provider backstop. If the Management server is unreachable, llm_limit_check fails open, meaning a caller might reach any model in the provider's union allowed by other groups.
    • Streaming: SSE streaming requires the parser to handle partial chunks without full buffering.

  12. Understand the NetBird LLM Proxy Middleware Chain

    main

    The NetBird LLM proxy uses a sequence of specialized middlewares to process HTTP requests and responses for LLM calls. This chain handles everything from parsing the initial request to enforcing usage limits and recording costs.

    The Canonical Execution Order:

    1. llm_request_parser: Parses the incoming request and extracts metadata.
    2. llm_router: Routes the request to the appropriate upstream provider based on model and configuration.
    3. llm_limit_check: Checks against management policies to allow or deny the request (e.g., token caps).
    4. llm_identity_inject: Injects identity/attribution metadata into headers or the request body.
    5. llm_guardrail: Enforces model allowlists and performs security checks.
    6. upstream LLM call: The actual request to the LLM provider.
    7. llm_response_parser: Parses the LLM response to extract token usage and completion text.
    8. cost_meter: Calculates the monetary cost based on usage.
    9. llm_limit_record: Records the usage back to the management server for billing and quota tracking.

    Critical Invariant: The Limit Check/Record Pair llm_limit_check and llm_limit_record must be used together. The limit_check middleware stamps the request with attribution metadata (User/Group/Window), which the limit_record middleware then reads from the response to ensure usage is correctly attributed in the database.