diff --git a/public/docs-static/img/agent-network/global-limits/agent-network-create-global-limit.png b/public/docs-static/img/agent-network/global-limits/agent-network-create-global-limit.png new file mode 100644 index 00000000..964ad3aa Binary files /dev/null and b/public/docs-static/img/agent-network/global-limits/agent-network-create-global-limit.png differ diff --git a/public/docs-static/img/agent-network/global-limits/agent-network-global-limits-list.png b/public/docs-static/img/agent-network/global-limits/agent-network-global-limits-list.png new file mode 100644 index 00000000..e39677d9 Binary files /dev/null and b/public/docs-static/img/agent-network/global-limits/agent-network-global-limits-list.png differ diff --git a/public/docs-static/img/agent-network/how-it-works/agent-network-diagram-internal-resources.png b/public/docs-static/img/agent-network/how-it-works/agent-network-diagram-internal-resources.png new file mode 100644 index 00000000..6389a59c Binary files /dev/null and b/public/docs-static/img/agent-network/how-it-works/agent-network-diagram-internal-resources.png differ diff --git a/public/docs-static/img/agent-network/how-it-works/agent-network-diagram-llm-apis.png b/public/docs-static/img/agent-network/how-it-works/agent-network-diagram-llm-apis.png new file mode 100644 index 00000000..c990086e Binary files /dev/null and b/public/docs-static/img/agent-network/how-it-works/agent-network-diagram-llm-apis.png differ diff --git a/public/docs-static/img/agent-network/integrations/agent-network-connect-anthropic.png b/public/docs-static/img/agent-network/integrations/agent-network-connect-anthropic.png new file mode 100644 index 00000000..16b8ac30 Binary files /dev/null and b/public/docs-static/img/agent-network/integrations/agent-network-connect-anthropic.png differ diff --git a/public/docs-static/img/agent-network/integrations/agent-network-connect-litellm.png b/public/docs-static/img/agent-network/integrations/agent-network-connect-litellm.png new file mode 100644 index 00000000..cfa45cab Binary files /dev/null and b/public/docs-static/img/agent-network/integrations/agent-network-connect-litellm.png differ diff --git a/public/docs-static/img/agent-network/integrations/agent-network-connect-openai.png b/public/docs-static/img/agent-network/integrations/agent-network-connect-openai.png new file mode 100644 index 00000000..f77c7182 Binary files /dev/null and b/public/docs-static/img/agent-network/integrations/agent-network-connect-openai.png differ diff --git a/public/docs-static/img/agent-network/integrations/agent-network-create-policy-codex.png b/public/docs-static/img/agent-network/integrations/agent-network-create-policy-codex.png new file mode 100644 index 00000000..3d158078 Binary files /dev/null and b/public/docs-static/img/agent-network/integrations/agent-network-create-policy-codex.png differ diff --git a/public/docs-static/img/agent-network/integrations/agent-network-create-policy-litellm.png b/public/docs-static/img/agent-network/integrations/agent-network-create-policy-litellm.png new file mode 100644 index 00000000..2c1b10e1 Binary files /dev/null and b/public/docs-static/img/agent-network/integrations/agent-network-create-policy-litellm.png differ diff --git a/public/docs-static/img/agent-network/integrations/agent-network-create-policy.png b/public/docs-static/img/agent-network/integrations/agent-network-create-policy.png new file mode 100644 index 00000000..3676b8d6 Binary files /dev/null and b/public/docs-static/img/agent-network/integrations/agent-network-create-policy.png differ diff --git a/public/docs-static/img/agent-network/integrations/agent-network-litellm-access-logs.png b/public/docs-static/img/agent-network/integrations/agent-network-litellm-access-logs.png new file mode 100644 index 00000000..8584645b Binary files /dev/null and b/public/docs-static/img/agent-network/integrations/agent-network-litellm-access-logs.png differ diff --git a/public/docs-static/img/agent-network/integrations/agent-network-litellm-tag-management.png b/public/docs-static/img/agent-network/integrations/agent-network-litellm-tag-management.png new file mode 100644 index 00000000..41152726 Binary files /dev/null and b/public/docs-static/img/agent-network/integrations/agent-network-litellm-tag-management.png differ diff --git a/public/docs-static/img/agent-network/integrations/agent-network-litellm-tag-usage.png b/public/docs-static/img/agent-network/integrations/agent-network-litellm-tag-usage.png new file mode 100644 index 00000000..adb1bd32 Binary files /dev/null and b/public/docs-static/img/agent-network/integrations/agent-network-litellm-tag-usage.png differ diff --git a/public/docs-static/img/agent-network/overview/agent-network-control-center-v2.png b/public/docs-static/img/agent-network/overview/agent-network-control-center-v2.png new file mode 100644 index 00000000..348d3881 Binary files /dev/null and b/public/docs-static/img/agent-network/overview/agent-network-control-center-v2.png differ diff --git a/public/docs-static/img/agent-network/overview/agent-network-control-center.png b/public/docs-static/img/agent-network/overview/agent-network-control-center.png new file mode 100644 index 00000000..53442130 Binary files /dev/null and b/public/docs-static/img/agent-network/overview/agent-network-control-center.png differ diff --git a/public/docs-static/img/agent-network/overview/agent-network-internal-resources-policy.png b/public/docs-static/img/agent-network/overview/agent-network-internal-resources-policy.png new file mode 100644 index 00000000..537b3fab Binary files /dev/null and b/public/docs-static/img/agent-network/overview/agent-network-internal-resources-policy.png differ diff --git a/public/docs-static/img/agent-network/overview/agent-network-llm-policy.png b/public/docs-static/img/agent-network/overview/agent-network-llm-policy.png new file mode 100644 index 00000000..c029ed72 Binary files /dev/null and b/public/docs-static/img/agent-network/overview/agent-network-llm-policy.png differ diff --git a/public/docs-static/img/agent-network/policies/agent-network-access-log.png b/public/docs-static/img/agent-network/policies/agent-network-access-log.png new file mode 100644 index 00000000..511a545f Binary files /dev/null and b/public/docs-static/img/agent-network/policies/agent-network-access-log.png differ diff --git a/public/docs-static/img/agent-network/policies/agent-network-create-policy.png b/public/docs-static/img/agent-network/policies/agent-network-create-policy.png new file mode 100644 index 00000000..af697aa2 Binary files /dev/null and b/public/docs-static/img/agent-network/policies/agent-network-create-policy.png differ diff --git a/public/docs-static/img/agent-network/policies/agent-network-guardrails.png b/public/docs-static/img/agent-network/policies/agent-network-guardrails.png new file mode 100644 index 00000000..a57c8772 Binary files /dev/null and b/public/docs-static/img/agent-network/policies/agent-network-guardrails.png differ diff --git a/public/docs-static/img/agent-network/policies/agent-network-policy-limits.png b/public/docs-static/img/agent-network/policies/agent-network-policy-limits.png new file mode 100644 index 00000000..f5a73f4e Binary files /dev/null and b/public/docs-static/img/agent-network/policies/agent-network-policy-limits.png differ diff --git a/public/docs-static/img/agent-network/providers/agent-network-create-provider.png b/public/docs-static/img/agent-network/providers/agent-network-create-provider.png new file mode 100644 index 00000000..80968d18 Binary files /dev/null and b/public/docs-static/img/agent-network/providers/agent-network-create-provider.png differ diff --git a/public/docs-static/img/agent-network/providers/agent-network-providers-list.png b/public/docs-static/img/agent-network/providers/agent-network-providers-list.png new file mode 100644 index 00000000..4175febf Binary files /dev/null and b/public/docs-static/img/agent-network/providers/agent-network-providers-list.png differ diff --git a/public/docs-static/img/agent-network/quickstart/agent-network-add-policy.png b/public/docs-static/img/agent-network/quickstart/agent-network-add-policy.png new file mode 100644 index 00000000..c029ed72 Binary files /dev/null and b/public/docs-static/img/agent-network/quickstart/agent-network-add-policy.png differ diff --git a/public/docs-static/img/agent-network/quickstart/agent-network-add-provider.png b/public/docs-static/img/agent-network/quickstart/agent-network-add-provider.png new file mode 100644 index 00000000..46428df2 Binary files /dev/null and b/public/docs-static/img/agent-network/quickstart/agent-network-add-provider.png differ diff --git a/public/docs-static/img/agent-network/quickstart/agent-network-agent-config.png b/public/docs-static/img/agent-network/quickstart/agent-network-agent-config.png new file mode 100644 index 00000000..925bf2a6 Binary files /dev/null and b/public/docs-static/img/agent-network/quickstart/agent-network-agent-config.png differ diff --git a/public/docs-static/img/agent-network/quickstart/agent-network-connect-device.png b/public/docs-static/img/agent-network/quickstart/agent-network-connect-device.png new file mode 100644 index 00000000..1023cb98 Binary files /dev/null and b/public/docs-static/img/agent-network/quickstart/agent-network-connect-device.png differ diff --git a/public/docs-static/img/agent-network/quickstart/agent-network-empty-endpoint.png b/public/docs-static/img/agent-network/quickstart/agent-network-empty-endpoint.png new file mode 100644 index 00000000..5bc598cc Binary files /dev/null and b/public/docs-static/img/agent-network/quickstart/agent-network-empty-endpoint.png differ diff --git a/public/docs-static/img/agent-network/quickstart/agent-network-endpoint.png b/public/docs-static/img/agent-network/quickstart/agent-network-endpoint.png new file mode 100644 index 00000000..6d8c805e Binary files /dev/null and b/public/docs-static/img/agent-network/quickstart/agent-network-endpoint.png differ diff --git a/public/docs-static/img/agent-network/quickstart/agent-network-usage-and-logs.png b/public/docs-static/img/agent-network/quickstart/agent-network-usage-and-logs.png new file mode 100644 index 00000000..81e594a8 Binary files /dev/null and b/public/docs-static/img/agent-network/quickstart/agent-network-usage-and-logs.png differ diff --git a/public/docs-static/img/agent-network/usage-and-logs/agent-network-access-log-filters.png b/public/docs-static/img/agent-network/usage-and-logs/agent-network-access-log-filters.png new file mode 100644 index 00000000..25b99199 Binary files /dev/null and b/public/docs-static/img/agent-network/usage-and-logs/agent-network-access-log-filters.png differ diff --git a/public/docs-static/img/agent-network/usage-and-logs/agent-network-access-logs.png b/public/docs-static/img/agent-network/usage-and-logs/agent-network-access-logs.png new file mode 100644 index 00000000..17d85341 Binary files /dev/null and b/public/docs-static/img/agent-network/usage-and-logs/agent-network-access-logs.png differ diff --git a/public/docs-static/img/agent-network/usage-and-logs/agent-network-log-collection.png b/public/docs-static/img/agent-network/usage-and-logs/agent-network-log-collection.png new file mode 100644 index 00000000..e3f80f0a Binary files /dev/null and b/public/docs-static/img/agent-network/usage-and-logs/agent-network-log-collection.png differ diff --git a/public/docs-static/img/agent-network/usage-and-logs/agent-network-usage-overview.png b/public/docs-static/img/agent-network/usage-and-logs/agent-network-usage-overview.png new file mode 100644 index 00000000..3d934340 Binary files /dev/null and b/public/docs-static/img/agent-network/usage-and-logs/agent-network-usage-overview.png differ diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index b9d94f50..50869c97 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -76,6 +76,54 @@ export const docsNavigation = [ { title: 'CLI', href: '/get-started/cli' }, ], }, + { + title: 'AGENT NETWORK', + links: [ + { title: 'What is Agent Network?', href: '/agent-network' }, + { title: 'How It Works', href: '/agent-network/how-it-works' }, + { title: 'Quickstart', href: '/agent-network/quickstart' }, + { title: 'Providers', href: '/agent-network/providers' }, + { + title: 'Policies', + href: '/agent-network/policies', + links: [ + { + title: 'Token & Budget Limits', + href: '/agent-network/policies/limits', + }, + { title: 'Guardrails', href: '/agent-network/policies/guardrails' }, + ], + }, + { + title: 'Usage & Logs', + href: '/agent-network/usage-and-logs', + links: [ + { + title: 'Usage Overview', + href: '/agent-network/usage-and-logs/usage-overview', + }, + { + title: 'Access Logs', + href: '/agent-network/usage-and-logs/access-logs', + }, + { + title: 'Log Collection & Retention', + href: '/agent-network/usage-and-logs/log-collection', + }, + ], + }, + { title: 'Global Limits', href: '/agent-network/global-limits' }, + { + title: 'Integrations', + href: '/agent-network/integrations', + links: [ + { title: 'Claude Code', href: '/agent-network/integrations/claude-code' }, + { title: 'Codex', href: '/agent-network/integrations/codex' }, + { title: 'LiteLLM', href: '/agent-network/integrations/litellm' }, + ], + }, + ], + }, { title: 'MANAGE NETBIRD', links: [ diff --git a/src/pages/agent-network/global-limits.mdx b/src/pages/agent-network/global-limits.mdx new file mode 100644 index 00000000..41414a63 --- /dev/null +++ b/src/pages/agent-network/global-limits.mdx @@ -0,0 +1,70 @@ +export const description = + 'Account-wide token and spend caps applied across every Agent Network policy, scoped to groups or users or left account-wide.' + +# Global Limits + +Global limits are account-wide caps on token usage and spend that apply across +**every** policy and **every provider** — a backstop independent of any single policy's +limits. They are **limit-only** rules: unlike a policy, a global limit never selects a +provider or authorizes traffic, and it isn't tied to one. It caps a caller's total +consumption no matter which provider or gateway the request is routed to. + +

+ agent network global limits list +

+ +A global limit acts as an **always-on ceiling**. It is evaluated before any policy, +on every request, and every applicable rule must pass. Because rules can only tighten a +caller's effective limit and never loosen it, adding one is always safe. + +## Scope + +Each rule targets who it applies to: + +- **Target groups** — the rule binds when the caller's groups intersect the rule's groups. +- **Target users** — the rule binds a specific user directly. +- **Untargeted** — a rule with no target groups or users applies to **every** caller (the + account-wide default). + +A request can be bound by several rules at once (for example an account-wide rule plus a +group-specific one); all of them are enforced. + +## Caps and Windows + +A global limit carries the same cap shape as a [policy limit](/agent-network/policies/limits): + +- A **token cap** and/or a **budget (USD) cap**. +- Each cap can be set **per user** and/or **per group**, over a fixed **window**. + +Windows and counting work exactly as described in +[Token & Budget Limits](/agent-network/policies/limits#how-the-window-works): caps apply to +a fixed, epoch-aligned window, and the check is run **before** the request against usage +already accumulated — so a request that starts under the cap is allowed even if it crosses +it, and the next one is blocked. + +## How Enforcement Works + +On every request, NetBird first evaluates all global limits that bind the caller. Each +applicable rule must pass; the first rule whose token or budget cap is exhausted denies the +request, before any policy is considered. The denial surfaces in the +[access logs](/agent-network/usage-and-logs/access-logs) as a **Token limit exceeded** or +**Budget limit exceeded** reason. For per-group caps, usage is attributed to the lowest +matching target group. + +## How It Combines with Policy Limits + +Global limits and [policy limits](/agent-network/policies/limits) are enforced together: a +request must pass **both** the global ceiling and the selected policy's own limits. Because +every applicable cap binds and the most restrictive one wins, a global limit can only +tighten what a policy allows, never widen it. Use global limits to set an overall account +ceiling, and policy limits for finer-grained, per-policy control. + +## Create a Global Limit + +Go to **Agent Network → Configuration → Global Limits** and add a rule with the token +and/or budget caps and an optional target. Leave the target empty to apply it account-wide, +or pick groups or users to scope it. + +

+ create global limit modal with token and budget caps +

\ No newline at end of file diff --git a/src/pages/agent-network/how-it-works.mdx b/src/pages/agent-network/how-it-works.mdx new file mode 100644 index 00000000..edb6527d --- /dev/null +++ b/src/pages/agent-network/how-it-works.mdx @@ -0,0 +1,237 @@ +import { Note } from '@/components/mdx' + +export const description = + 'How NetBird Agent Network works: the architecture behind keyless, identity-based access to LLM APIs and internal resources, and the lifecycle of a single agent request from the tunnel through routing, policy, and key injection to the upstream provider.' + +# How Agent Network Works + +Agent Network gives every agent a real identity and governs what it can reach over +NetBird's encrypted overlay. It works along two paths, depending on what the agent is +calling: + +- **LLM APIs and AI gateways** are reached through a single **agent network endpoint** + served by the NetBird proxy. It sits between your agents and the APIs they call. You + point your agent at that endpoint instead of the provider's URL, and the proxy ties + each request to an identity, evaluates it against your policies, enforcing token and + budget limits, quotas, and model guardrails. It also injects the upstream provider key + server-side, forwards the request, and records usage and cost for every call. +- **Internal resources** such as databases, internal APIs, and self-hosted models, are + reached directly over **peer-to-peer WireGuard tunnels**, the same way any NetBird peer + reaches another. This traffic is governed by the same identities and access policies + but does not pass through the proxy, so there is no endpoint or key injection — the + agent connects straight to the resource over the overlay. + +## Architecture + +Agent Network is built on two existing NetBird capabilities: the **overlay network** +(an encrypted WireGuard mesh between peers) and the **reverse proxy** (a peer that +terminates requests and forwards them to upstreams). Around those, the management +service adds an identity-aware control plane for AI traffic. + +### LLM APIs and AI Gateways + +The diagram below illustrates the **first path** — an LLM request: the agent reaches the +endpoint over the WireGuard overlay, the proxy enforces identity, policies, limits, and guardrails +against the management control plane, injects the provider key, and forwards to the +upstream API or gateway. The proxy can also inject the calling agent's identity into the +request, so the gateway itself can attribute usage and enforce its own limits based on the +agent's group membership. For example, with a LiteLLM gateway it writes the agent's IdP groups +into `metadata.tags` and its identity into the `x-litellm-end-user-id` header, so LiteLLM +can apply tag budgets and per-user attribution. + +

+ agent network LLM request path through the NetBird proxy +

+ +- **NetBird client** — the agent's device joins the overlay as a peer. Its requests to + the endpoint are routed through the WireGuard tunnel, not the public internet. +- **Proxy peer** — handles LLM traffic only. It terminates the request, establishes + the caller's identity, runs the routing and policy pipeline, injects the provider key, + and forwards to the upstream API or gateway. +- **Management service** — the control plane. It holds providers, policies, guardrails, + and limits; resolves identities against your IdP; answers the proxy's per-request + policy checks; and records usage and access logs. +- **Identity provider** — your existing IdP (Okta, Microsoft Entra ID, Google, …) + supplies the identities and group memberships that policies are written against. +- **Upstreams** — for LLM traffic, the proxy forwards to LLM APIs and AI gateways. + +The endpoint hostname itself (for example `https://sailcloth.netbird.ai`) is generated +when you connect your first provider and is only reachable from inside your overlay. +It applies to LLM traffic only; internal resources keep their normal peer addresses on the +overlay. + +### Internal Resources + +The **second path** covers everything that isn't an LLM API — internal databases, +internal APIs, and self-hosted models on a GPU host. Here the proxy is not involved at +all. The agent connects to the target's overlay address **directly over a peer-to-peer +WireGuard tunnel**, exactly the way any NetBird peer reaches another. Access is still +identity-based: the agent's peer identity and group membership are matched against your +access policies, so it can reach only the resources it is authorized for. Because the +traffic never passes through the proxy, this path has no agent network endpoint, no +provider-key injection, and no token, budget, or per-request LLM logging — it is governed +like standard NetBird peer-to-peer access. This keeps internal traffic fast and private, +flowing straight between the two peers. Because NetBird is a peer-to-peer network, this +also works in reverse, so a resource can reach back to an agent when needed, such as to +deliver a callback or webhook. + +

+ agent network internal resource request path through WireGuard overlay +

+ +## The Lifecycle of an LLM Request + +This pipeline applies to LLM traffic — requests to the agent network endpoint. +Access to internal resources skips it entirely and flows peer-to-peer (see [Internal +Resources](#internal-resources)). + +The proxy runs each request through an ordered chain of middleware. On the way to the +upstream: + +1. **Establish identity.** The request arrives over the WireGuard tunnel, so the proxy + maps it to the calling NetBird peer and its identity — tied to your IdP for a human + user, or the peer's own NetBird identity for an autonomous agent — together with its + group membership. See [Identity and Authentication](#identity-and-authentication). +2. **Parse the request.** Read the target model and stream flag from the body, and + capture the prompt if prompt collection is enabled. +3. **Route and inject the key.** Match the model to a provider the caller's groups are + authorized to use, rewrite the upstream target, strip any client-supplied auth headers, + and inject the provider's key from server-side storage — see + [Routing](#routing-matching-a-request-to-a-provider) and [Keyless Access](#keyless-access). +4. **Check policy and limits.** Ask management to select the matching policy and evaluate + account- and policy-level token and budget caps. If unauthorized or a cap is exhausted, + the request is denied here — see [Policies, Limits, and + Guardrails](#policies-limits-and-guardrails). +5. **Stamp identity for the gateway.** Add the caller's identity to the upstream request + (for example into `metadata.tags` and `x-litellm-end-user-id`) for gateways that key + their own budgets and attribution off it. +6. **Apply guardrails.** Enforce the model allowlist and the prompt-capture rules. + +The request is then forwarded to the upstream API or gateway. On the response leg, in +reverse: + +7. **Meter.** Extract token counts from the response and convert them to cost. +8. **Record.** Post the usage back to management to update the limit counters. Usage is + always recorded; a full access-log entry is written when log collection is on — see + [Usage and Access Logs](#usage-and-access-logs). + +A denial at any gate returns `403` to the client with a machine-readable reason, and the +request is still recorded so it appears in your logs. + +## Identity and Authentication + +Every request is tied to a real identity before any policy runs, and that identity always +comes from the **NetBird tunnel**. Because the request arrives over WireGuard, the proxy +maps its source to the enrolled peer and resolves the peer's NetBird identity and group +membership: + +- For a **human user** — for example someone running Claude Code — the NetBird identity is + tied to your identity provider (Okta, Microsoft Entra ID, Google, …), so the request + carries that user and the groups they belong to. +- For an **autonomous agent**, the identity is the agent's own NetBird peer identity and + the groups assigned to that peer. + +Either way the request carries a real identity and its **group membership**, captured at +request time. There is no API key or separate login on the client — the tunnel is the +credential. Policies are written against those groups, so access to AI follows the same +identities your organization already manages. + +## Routing: Matching a Request to a Provider + +A request names a model (for example `claude-opus-4-8` or `gpt-4o`). The router picks the +provider to serve it by: + +1. **Model claim.** Keeping providers whose allowed-models list includes the requested + model. A provider with no model list acts as a catch-all gateway. +2. **Group authorization.** Keeping only providers the caller's groups are allowed to + reach. This authorization is compiled from your policies, so a provider is reachable + only where a policy grants it. +3. **Specificity.** Preferring a same-vendor, explicitly-claimed model over a catch-all + gateway. + +If no provider claims the model, the request is denied as **model not available**. If a +provider claims it but the caller's groups aren't authorized, it's denied as **no +authorized provider**. When a route is found, the proxy records which configured provider +was selected and which groups authorized it. + +## Policies, Limits, and Guardrails + +Routing decides *where* a request can go; policies decide *whether it may* and *under what +budget*. By default nothing is allowed — a policy must connect a **source group** to one +or more **providers**. + +At request time, management evaluates, in order: + +- **Account ceilings.** Account-wide budget rules are checked first. If an account-level + token or budget cap is exhausted, the request is denied regardless of policy. +- **Applicable policies.** Among enabled policies whose providers include the selected + provider and whose source groups intersect the caller's groups, management picks one to + attribute the request to. Uncapped policies and larger remaining budgets are preferred, + with deterministic tie-breaking, so requests drain the most appropriate bucket first. +- **Limits.** A policy may cap **tokens** or **spend** per user and/or per group over a + rolling time window. Usage is accumulated in windowed counters aligned to a fixed epoch, + so the same totals hold across a clustered deployment. +- **Guardrails.** A policy can attach guardrails such as a **model allowlist** (reject + models outside the list) and **prompt capture** controls. + +Each denial carries a reason that surfaces in the access log: + +| Reason | Meaning | +| --- | --- | +| Model not available | No provider is configured to serve the requested model | +| No authorized provider | A provider serves the model, but the caller's groups aren't allowed | +| Model not allowed | A guardrail's model allowlist rejected the model | +| Token limit exceeded | A policy or account token cap is exhausted for the window | +| Budget limit exceeded | A policy or account spend cap is exhausted for the window | + +See [Policies](/agent-network/policies) and [Global Limits](/agent-network/global-limits) +for how to configure these. + +## Keyless Access + +Provider API keys live only on the server. When you connect a provider, its key is stored +encrypted by the management service. During a request the proxy **strips** any +client-supplied authorization headers (`Authorization`, `x-api-key`, and similar) and +**injects** the provider's key on the way to the upstream. + +The practical effect: agents authenticate to NetBird with their NetBird identity, never +with a provider key. Keys can't leak from a client because clients never hold them, and +rotating a provider key is a single server-side change. + +## Usage and Access Logs + +Agent Network separates lightweight accounting from full audit detail: + +- **Usage** is recorded for **every** served request — identity, provider, model, tokens, + and cost — regardless of any logging setting. This always-on stream powers the usage + dashboards and the limit counters, and is retained indefinitely. +- **Access logs** add the full per-request detail (method, path, status, duration, and — + when prompt capture is on — the prompt and completion). Full access-log entries are + written only when **log collection** is enabled for the account, and are swept after a + configurable **retention period**. Prompts can be redacted for PII. + +See [Usage & Logs](/agent-network/usage-and-logs) for the dashboards and controls. + +## The Overlay Network + +The transport underneath all of this is NetBird's WireGuard overlay. The agent's device +is a peer, the proxy is a peer, and connections are established **directly between peers**. +Because WireGuard is UDP-based and peer-to-peer, the overlay traverses NAT and firewalls +without opening inbound ports, changing security groups, or altering network topology. + +This is also where the two paths differ: + +- **LLM traffic** rides the overlay to reach the **proxy** peer, which then applies the + pipeline above and forwards to the upstream API or gateway. +- **Internal resources** — databases, APIs, and self-hosted models — are reached over a + **direct peer-to-peer tunnel** between the agent and the target peer, with no proxy in + between. Access is governed by the same identities and access policies as any other + NetBird peer, so an agent reaches only the resources its identity is allowed to. + +## Next steps + +- [Quickstart](/agent-network/quickstart). Deploy Agent Network and make your first keyless call. +- [Providers](/agent-network/providers). Connect LLM APIs, gateways, and local models. +- [Policies](/agent-network/policies). Authorize identities and attach limits and guardrails. +- [Usage & Logs](/agent-network/usage-and-logs). Track cost, usage, and per-request audit. diff --git a/src/pages/agent-network/index.mdx b/src/pages/agent-network/index.mdx new file mode 100644 index 00000000..1ee93521 --- /dev/null +++ b/src/pages/agent-network/index.mdx @@ -0,0 +1,84 @@ +import { Note } from '@/components/mdx' + +export const description = + 'Agent Network is NetBird\'s control layer for AI agents — a keyless gateway to LLM APIs and scoped, identity-based access to your internal resources, all over the tunnel with per-identity policies, limits, and audit.' + +# What is NetBird Agent Network? + +As AI spreads across organizations, humans, agents, tools, and workflows need access to LLM APIs +and internal systems. Too often, that access relies on shared API keys and broad network paths, creating credential +sprawl, weak identity, poor visibility, and limited control over cost, usage, and what each agent can reach. It echoes how SSH keys are still managed in many places: shared, copied onto machines by +hand, and never revoked when people move on. + +Agent Network is NetBird's access control layer for AI agents and the people who run them. It gives every agent a +real identity, tied to an identity provider (IdP), and governs what it can reach: +LLM APIs and AI gateways it can call, and the internal resources it can access. Traffic +flows only over the encrypted NetBird tunnel, scoped by policy, with no API keys or other credentials +to leak. + +The NetBird Control Center below captures it in essence: the agents on the left reach the internal +databases, servers, and LLM APIs on the right, only where the policies in the middle +allow it. + +

+ agent network +

+ + + Agent Network is currently in Beta. It is open source and can be self-hosted on your own infrastructure. + See the [GitHub repo](https://github.com/netbirdio/netbird/agent-network) for more details. + + +## Two Use Cases + +Agent Network is built on NetBird’s overlay network and reverse-proxy capabilities, giving any AI agent secure access +to LLM APIs and private resources. It works with human-in-the-loop tools like Claude Code and Codex, as well as fully autonomous +workloads running on VMs, Mac minis, or other infrastructure. Below are two specific use cases where Agent Network fits naturally. + +### Keyless Access to LLM APIs for Cost Control and Auditing + +Your agents reach OpenAI, Anthropic, and AI gateways through a single +endpoint that's only reachable over the end-to-end encrypted tunnel. There is no need to +store or share API keys or other credentials. NetBird holds the provider API +key server-side, so it never reaches the caller, and every request is tied to a +real identity from your identity provider like Okta, Microsoft Entra ID, Google, +and others. That lets you apply per-identity policies, token and cost limits, model guardrails, and +full audit logs to outbound LLM traffic. + +

+ agent network llm policy +

+ +### Agentic Access to Internal Resources and Local Models + +Similarly, agents can securely reach internal resources such as databases, APIs, and private services that are not +exposed to the internet. This also covers private models served by Ollama, vLLM, or GPU clusters, giving agents secure +access over the same tunnel without public exposure. + +NetBird’s overlay network traverses firewalls and works across datacenters and cloud environments without opening ports, +configuring security groups, or changing network topology. Each agent connects with its own identity, and access policies +define exactly which resources it can reach, just like any other NetBird peer in the network. + +

+ agent network llm policy +

+ +## How NetBird Fits in Your Enterprise IT Stack + +It’s common for organizations to rely on a centralized identity provider like Okta, Microsoft Entra ID, Google, or others. +It’s also common for IT teams to manage access to internal resources while keeping costs under control. + +Traditionally, IT has done this through the internal network, using ZTNA or VPNs to give employees access to databases, web servers, +internal APIs, and other private services. + +AI agents should be treated the same way: as another entity accessing the network. They need secure access to +internal resources, and modern enterprise resources now include LLMs and API endpoints alongside traditional infrastructure. +That makes agent access a natural responsibility for IT. + +Because NetBird connects seamlessly with existing identity providers, IT teams can integrate NetBird Agent Network into +their enterprise stack with minimal changes. + +## Next steps + +- [Quickstart](/agent-network/quickstart). Deploy NetBird Agent Network and make your first routed LLM call. +- [How Agent Network Works](/agent-network/how-it-works). Understand the core concepts and architecture of Agent Network. \ No newline at end of file diff --git a/src/pages/agent-network/integrations/claude-code.mdx b/src/pages/agent-network/integrations/claude-code.mdx new file mode 100644 index 00000000..45f74591 --- /dev/null +++ b/src/pages/agent-network/integrations/claude-code.mdx @@ -0,0 +1,91 @@ +export const description = + 'Route Claude Code through NetBird Agent Network by pointing it at your agent network endpoint as the Anthropic base URL — no API key on the client.' + +# Keyless Access to Claude Code + +Point Claude Code at your [agent network endpoint](/agent-network/how-it-works#llm-apis-and-ai-gateways) +as its Anthropic base URL. NetBird holds the Anthropic API key server-side, so no key lives +on your machine. + +Running Claude Code through Agent Network turns it from a tool that needs a shared +Anthropic key into one your team reaches with their existing identity: + +- **Keyless access through your IdP.** No Anthropic API key is distributed to or stored on + any developer's machine. Each person runs Claude Code over the NetBird tunnel, and the + request is tied to their real identity from your identity provider (Okta, Microsoft + Entra ID, Google, …). Onboarding and offboarding follow the same IdP groups you already + manage — there's no key to hand out, copy, or revoke. +- **Usage tracking per developer and group.** Every request is metered by identity, model, + tokens, and cost, so you can see exactly who is using Claude Code and how much it costs, + broken down per person and aggregated per IdP group (team, department, project) in + [Usage & Logs](/agent-network/usage-and-logs). +- **Budget and token limits.** Attach per-user or per-group token and spend caps over a + rolling window in your [policies](/agent-network/policies), so Claude Code usage stays + within budget and a single user can't run up the whole account's bill. + +The rest of this page walks through connecting the provider and pointing Claude Code at +your endpoint. + +## Connect the Provider + +1. Go to **Agent Network → Providers** and click **Connect Provider**. +2. Select **Anthropic** and paste your Anthropic API key. +3. Save the provider. The key is now held server-side — the next step authorizes who can use it. + +

+ connect Anthropic provider in NetBird Agent Network +

+ +See [Providers](/agent-network/providers) for details. + +## Create a Policy + +By default nothing is allowed — a policy must connect a source group to the Anthropic +provider before anyone can route Claude Code through it. + +1. Go to **Agent Network → Policies** and add a policy. +2. Set the **Source** to the users or agents who should be able to use Claude Code (for example + your `Engineering` group from your IdP). +3. Set the **Provider** to the Anthropic provider you just connected. +4. Optionally attach per-user or per-group [token and budget limits](/agent-network/policies/limits) + so Claude Code usage stays within budget, and [guardrails](/agent-network/policies/guardrails) + such as a model allowlist. + +

+ create a NetBird Agent Network policy authorizing Claude Code +

+ +See [Policies](/agent-network/policies) for details. + +## Configure with `settings.json` + +Add the following to `~/.claude/settings.json`. The `apiKeyHelper` returns a dummy value so +Claude Code doesn't prompt for a key — NetBird supplies the real one. + +```json +{ + "apiKeyHelper": "echo '-'", + "env": { + "ANTHROPIC_BASE_URL": "https://" + } +} +``` + +## Configure with Shell Variables + +Alternatively, export the variables before launching Claude Code: + +```bash +export ANTHROPIC_BASE_URL=https:// +export ANTHROPIC_API_KEY=none +claude +``` + +That's it — Claude Code now sends every request over the NetBird tunnel, where it's tied to +your identity, checked against your policies and limits, and recorded in +[Usage & Logs](/agent-network/usage-and-logs) — broken down per developer and aggregated +per IdP group. + +

+ NetBird Agent Network access logs showing per-request Claude Code identity, group, model, cost, and status +

diff --git a/src/pages/agent-network/integrations/codex.mdx b/src/pages/agent-network/integrations/codex.mdx new file mode 100644 index 00000000..3351b13c --- /dev/null +++ b/src/pages/agent-network/integrations/codex.mdx @@ -0,0 +1,78 @@ +export const description = + 'Point the Codex CLI at your NetBird Agent Network endpoint with a custom model provider — keyless, over the tunnel.' + +# Keyless Access to Codex + +Configure Codex with a custom model provider that points at your +[agent network endpoint](/agent-network/how-it-works#llm-apis-and-ai-gateways). NetBird +injects the upstream key server-side, so the client stays keyless. + +Running Codex through Agent Network turns it from a tool that needs a shared OpenAI key +into one your team reaches with their existing identity: + +- **Keyless access through your IdP.** No OpenAI API key is distributed to or stored on any + developer's machine. Each person runs Codex over the NetBird tunnel, and the request is + tied to their real identity from your identity provider (Okta, Microsoft Entra ID, + Google, …). Onboarding and offboarding follow the same IdP groups you already manage — + there's no key to hand out, copy, or revoke. +- **Usage tracking per developer and group.** Every request is metered by identity, model, + tokens, and cost, so you can see exactly who is using Codex and how much it costs, broken + down per person and aggregated per IdP group (team, department, project) in + [Usage & Logs](/agent-network/usage-and-logs). +- **Budget and token limits.** Attach per-user or per-group token and spend caps over a + rolling window in your [policies](/agent-network/policies), so Codex usage stays within + budget and a single user can't run up the whole account's bill. + +The rest of this page walks through connecting the provider and pointing Codex at your +endpoint. + +## Connect the Provider + +1. Go to **Agent Network → Providers** and click **Connect Provider**. +2. Select **OpenAI** (or another OpenAI-compatible provider or gateway) and paste its API key. +3. Save the provider. The key is now held server-side — the next step authorizes who can use it. + +

+ connect OpenAI provider in NetBird Agent Network +

+ +See [Providers](/agent-network/providers) for details. + +## Create a Policy + +By default nothing is allowed — a policy must connect a source group to the OpenAI provider +before anyone can route Codex through it. + +1. Go to **Agent Network → Policies** and add a policy. +2. Set the **Source** to the users or agents who should be able to use Codex (for example + your `Engineering` group from your IdP). +3. Set the **Provider** to the OpenAI provider you just connected. +4. Optionally attach per-user or per-group [token and budget limits](/agent-network/policies/limits) + so Codex usage stays within budget, and [guardrails](/agent-network/policies/guardrails) + such as a model allowlist. + +

+ create a NetBird Agent Network policy authorizing Codex +

+ +See [Policies](/agent-network/policies) for details. + +## Configure with `config.toml` + +Add a model provider to `~/.codex/config.toml` and select it as the default: + +```toml +model_provider = "netbird" + +[model_providers.netbird] +name = "NetBird" +base_url = "https:///v1" +wire_api = "responses" +``` + +`wire_api = "responses"` tells Codex to use the OpenAI Responses API that it expects. The +`/v1` suffix is the OpenAI-compatible base path on your endpoint. + +Once saved, Codex routes through NetBird, where each request is tied to your identity, +evaluated against your policies and limits, and recorded in +[Usage & Logs](/agent-network/usage-and-logs). diff --git a/src/pages/agent-network/integrations/index.mdx b/src/pages/agent-network/integrations/index.mdx new file mode 100644 index 00000000..8b79a172 --- /dev/null +++ b/src/pages/agent-network/integrations/index.mdx @@ -0,0 +1,19 @@ +export const description = + 'Connect specific agent tools and gateways to NetBird Agent Network — Claude Code, Codex, and LiteLLM.' + +# Integrations + +These guides show how to point common AI tools and gateways at your +[agent network endpoint](/agent-network/how-it-works#llm-apis-and-ai-gateways). In every +case the client holds no provider API key — NetBird authorizes the request against your +[policies](/agent-network/policies) and injects the upstream key server-side. + +Replace `` in the snippets below with the endpoint shown on the +**Agent Network → Providers** page after you connect your first provider. + +## In This Section + +- [Claude Code](/agent-network/integrations/claude-code) — route Claude Code through NetBird. +- [Codex](/agent-network/integrations/codex) — point the Codex CLI at the endpoint. +- [LiteLLM](/agent-network/integrations/litellm) — use a LiteLLM gateway with identity-based + attribution and budgets. diff --git a/src/pages/agent-network/integrations/litellm.mdx b/src/pages/agent-network/integrations/litellm.mdx new file mode 100644 index 00000000..5a2509d5 --- /dev/null +++ b/src/pages/agent-network/integrations/litellm.mdx @@ -0,0 +1,93 @@ +import { Note } from '@/components/mdx' + +export const description = + 'Use a LiteLLM gateway behind NetBird Agent Network: NetBird forwards the caller identity so LiteLLM can apply its own tag budgets and per-user attribution.' + +# LiteLLM + +LiteLLM is an AI gateway that routes to many upstream providers. You **self-host** it, +typically inside the same network as the NetBird proxy, so the proxy reaches it directly. +Connecting it behind NetBird gives you keyless access over the tunnel **and** lets LiteLLM +apply its own attribution and budgets, because NetBird forwards the caller's identity on +every request. + +## Connect LiteLLM as a Provider + +Because LiteLLM is self-hosted, the upstream URL points at your own instance. Host it in the +same network as the proxy so the proxy can reach it directly (for example +`https://litellm.internal`). + +1. Go to **Agent Network → Providers** and click **Connect Provider**. +2. Select **LiteLLM Proxy** and set the **Upstream URL** to your self-hosted LiteLLM instance. +3. Paste a LiteLLM **virtual key** as the API key. NetBird stores it server-side. +4. Save the provider. The key is now held server-side — the next step authorizes who can use it. + +

+ connect a self-hosted LiteLLM Proxy provider in NetBird Agent Network +

+ +## Create a Policy + +By default nothing is allowed — a policy must connect a source group to the LiteLLM provider +before anyone can route through it. + +1. Go to **Agent Network → Policies** and add a policy. +2. Set the **Source** to the users or agents who should be able to use LiteLLM (for example + your `Engineering` group from your IdP). +3. Set the **Provider** to the LiteLLM provider you just connected. +4. Optionally attach per-user or per-group [token and budget limits](/agent-network/policies/limits) + and [guardrails](/agent-network/policies/guardrails) such as a model allowlist. These are + enforced by NetBird before the request reaches LiteLLM, on top of LiteLLM's own budgets. + +

+ create a NetBird Agent Network policy authorizing LiteLLM +

+ +See [Policies](/agent-network/policies) for details. + +## How Identity Is Forwarded + +When the upstream is LiteLLM, NetBird maps the calling agent's identity onto the request so +the gateway can attribute usage and enforce its own controls: + +- **Groups** are written into `metadata.tags` in the JSON body, so LiteLLM can apply tag + budgets and rate limits. +- The **user identity** is sent in the `x-litellm-end-user-id` header. + +The proxy strips any client-supplied value first, so an app can't spoof its identity. + + + The configured key must be a LiteLLM **virtual key** with `metadata.allow_client_tags: true`, + otherwise LiteLLM silently drops the forwarded tags. + + +## View Group Usage in LiteLLM + +Because NetBird writes each caller's IdP groups into `metadata.tags`, those groups show up in +LiteLLM's own usage views as tags. In the LiteLLM UI, go to **Usage** and select the +**Tag Usage** view, then filter by a tag to see spend and requests for that group. In our +example, the `Engineering` group injected by NetBird appears here with its own +**Tag Spend Overview**. + +

+ LiteLLM Tag Usage view showing spend for the Engineering group injected by NetBird +

+ +You can see every group forwarded from NetBird under **Experimental → Tag Management**, where +each NetBird IdP group is listed as a tag passed dynamically in the request. + +

+ LiteLLM Tag Management listing the groups passed from NetBird, including Engineering +

+ +## Result + +Agents point at the NetBird endpoint with no key. NetBird enforces your policies, limits, +and guardrails first, then LiteLLM applies its own tag and end-user budgets on top — driven +by the same NetBird identity. Every call is recorded in +[Usage & Logs](/agent-network/usage-and-logs), where each LiteLLM request shows the caller's +identity, auth group, model, tokens, cost, and status. + +

+ NetBird Access Logs showing LiteLLM Proxy requests with the Engineering auth group +

diff --git a/src/pages/agent-network/policies/guardrails.mdx b/src/pages/agent-network/policies/guardrails.mdx new file mode 100644 index 00000000..542fc0a1 --- /dev/null +++ b/src/pages/agent-network/policies/guardrails.mdx @@ -0,0 +1,34 @@ +export const description = + 'Guardrails restrict which models a policy can use and control prompt capture, including PII redaction.' + +# Guardrails + +Guardrails are checks you configure on a policy to constrain what its callers can +do. They are defined per policy and apply only to that policy. + +

+ agent network guardrails on a policy +

+ +## Model Allowlist + +Restrict a policy to a specific set of models. Requests for any other model are +denied. + +## Prompt Capture + +Optionally store request prompts and response completions on logged requests. +Prompt capture only runs when **both** the account-level prompt collection +setting and a policy guardrail enable it — see +[Log Collection & Retention](/agent-network/usage-and-logs/log-collection). + +### PII Redaction + +When capture is enabled, you can strip personally identifiable information from +prompts and completions before they're stored. Effective redaction is the OR of +the account setting and the guardrail setting. + +## Configuring Guardrails + +Open the policy's **Guardrails** tab when creating or editing a policy and enable +the checks you want. They take effect for that policy only. \ No newline at end of file diff --git a/src/pages/agent-network/policies/index.mdx b/src/pages/agent-network/policies/index.mdx new file mode 100644 index 00000000..4c5af06e --- /dev/null +++ b/src/pages/agent-network/policies/index.mdx @@ -0,0 +1,61 @@ +export const description = + 'Policies connect users and agents to AI providers, with optional token and budget limits plus guardrails for LLM access.' + +# Policies + +Policies connect users and agents (source groups) to AI providers — controlling +which identities can reach which providers and models, with optional limits and +guardrails. + +

+ agent network llm policy +

+ + + This page explains how to create and manage access to AI providers and gateways. If you are + looking for a guide on how to manage access to internal resources, see + [Access Control](/manage/access-control). + + +## How Policies Work + +- **Source groups** — the users/agents the policy applies to. +- **Destination providers** — the providers the policy grants access to. +- **Limits** — optional per-user and per-group token and budget caps. +- **Guardrails** — optional model allowlist and prompt capture. + +A request is allowed when a policy connects the caller's groups to the resolved +provider and no applicable limit is exhausted. + +## Create a Policy + +1. Go to **Agent Network → Policies** and add a policy. +2. Choose the source groups and destination providers. +3. Optionally attach [limits](/agent-network/policies/limits) and + [guardrails](/agent-network/policies/guardrails). + +Try it out by calling your Agent Network endpoint. The access log will show the +policy in action: + +```bash +curl -vk https://sailcloth.netbird.ai/v1/chat/completions \ + --header "Content-Type: application/json" \ + --data '{ + "model": "gpt-5.5", + "messages": [ + { + "role": "user", + "content": "What is NetBird?" + } + ] + }' | jq +``` + +

+ agent network log +

+ +## More + +- [Token & Budget Limits](/agent-network/policies/limits) +- [Guardrails](/agent-network/policies/guardrails) \ No newline at end of file diff --git a/src/pages/agent-network/policies/limits.mdx b/src/pages/agent-network/policies/limits.mdx new file mode 100644 index 00000000..9ded33b9 --- /dev/null +++ b/src/pages/agent-network/policies/limits.mdx @@ -0,0 +1,75 @@ +export const description = + 'Cap LLM token usage and spend per user or per group within a policy, over a fixed time window.' + +# Token & Budget Limits + +Limits cap how much a policy's callers can consume. They come in two halves, +each enforceable per user and per group over a fixed time window. + +

+ agent network token and budget limits on a policy +

+ +To enable limits, open the policy's **Limits** tab when creating or editing a policy, turn +on the token and/or budget limit, and set the per-user and per-group caps and window. + +## Token Limits + +- **User cap** — maximum tokens per user in the window. +- **Group cap** — maximum tokens per group in the window. +- **Window** — the fixed period the cap applies to (see [below](#how-the-window-works)). + +## Budget Limits + +- **User cap (USD)** — maximum spend per user in the window. +- **Group cap (USD)** — maximum spend per group in the window. +- **Window** — the fixed period the cap applies to (see [below](#how-the-window-works)). + +## How the Window Works + +A cap applies to a **fixed window**, not a sliding one. NetBird divides time into +back-to-back buckets of the window's length, aligned to a fixed grid starting from the +Unix epoch (`1970-01-01T00:00:00Z`). Each request is counted into the bucket its timestamp +falls in, and the cap is compared against the total accumulated in the **current** bucket. +When the window rolls over to the next bucket, the counter effectively starts again at +zero. + +The bucket boundary is computed as: + +```text +window_start = floor(now / window) * window +``` + +This alignment is deliberate: because every node derives the same boundaries from the same +clock, usage adds up consistently across a clustered deployment instead of drifting with +each node's first request. + +**Example — a 1-hour (3600s) window.** Buckets run from the top of each hour in UTC: +`13:00:00–13:59:59`, `14:00:00–14:59:59`, and so on. A request at `13:45` counts toward the +`13:00` bucket; a request at `14:02` lands in a fresh `14:00` bucket with the counter back +at zero — regardless of when the user's first request of the day was. + +## How Enforcement Works + +Caps are checked **before** the request runs, against usage already accumulated in the +current window. The check is `used >= cap`: if the running total has not yet reached the +cap, the request is allowed; once it has, the request is denied with a reason surfaced in +the [access logs](/agent-network/usage-and-logs/access-logs). + +Because the check uses the total **before** the request (NetBird doesn't reserve or +pre-estimate the request's own cost), a single request can push usage past the cap. The +request that crosses the line still completes; the **next** one is blocked. + +**Example.** A token cap is set to `1000` for a group, and the group has used `999` in the +current window: + +- The next request is checked: `999 >= 1000` is false, so it **goes through** — even though + it then consumes, say, 250 tokens and pushes the total to `1249`. +- The following request is checked: `1249 >= 1000` is true, so it is **blocked** until the + window rolls over. + +So a cap is a floor for *when blocking starts*, not a hard ceiling on the exact total — plan +caps with a little headroom if you need a strict upper bound. + +For account-wide caps that apply across all policies, see +[Global Limits](/agent-network/global-limits). \ No newline at end of file diff --git a/src/pages/agent-network/providers.mdx b/src/pages/agent-network/providers.mdx new file mode 100644 index 00000000..199415d3 --- /dev/null +++ b/src/pages/agent-network/providers.mdx @@ -0,0 +1,86 @@ +export const description = + 'Connect AI providers and gateways — OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Google Vertex AI, Mistral, LiteLLM, Portkey, Bifrost, Cloudflare, Vercel, OpenRouter, or any OpenAI-compatible endpoint — to NetBird Agent Network and expose a single keyless endpoint.' + +# Providers + +A **provider** is an upstream LLM service that NetBird routes requests to. Connecting one +stores its API key server-side and exposes it through your keyless, tunnel-only +[agent network endpoint](/agent-network/how-it-works#llm-apis-and-ai-gateways), so agents +never hold a provider key. + +

+ agent network providers list +

+ +## Supported Providers + +When you connect a provider, the picker groups the catalog into first-party **AI +Providers**, multi-provider **AI Gateways**, and a **Custom** catch-all. + +### AI Providers + +First-party vendor APIs: + +- OpenAI +- Anthropic +- Azure OpenAI +- AWS Bedrock +- Google Vertex AI +- Mistral + +### AI Gateways + +Routing and aggregation layers that sit in front of multiple providers. NetBird can also +forward the calling agent's identity to these so the gateway can apply its own attribution +and budgets (see [How It Works](/agent-network/how-it-works#llm-apis-and-ai-gateways)): + +- LiteLLM Proxy +- Portkey AI Gateway +- Bifrost +- Cloudflare AI Gateway +- Vercel AI Gateway +- OpenRouter + +### Custom + +- Custom / Self-hosted — any OpenAI-compatible endpoint, including local models served by + Ollama, vLLM, or a private GPU host. + +## Connect a Provider + +1. Go to **Agent Network → Providers** and click **Connect Provider**. +2. Select the provider or gateway. NetBird pre-fills the upstream URL and the correct auth + header for that vendor. +3. Paste the provider's **API key**. It is stored encrypted server-side and never sent to + callers. +4. _(Optional)_ Restrict the **allowed models** and set **per-model pricing** used for cost + estimates in usage and logs. +5. _(Optional, gateways)_ Fill any gateway-specific fields (for example a Portkey config + ID) and the identity headers used for attribution. +6. Save the provider. + +

+ agent network connect provider modal +

+ +## Models and Pricing + +Each provider carries a list of models it serves. Leaving the list empty makes the +provider a catch-all that accepts any model (typical for gateways); listing specific models +restricts routing to them. Per-model input/output prices drive the cost figures shown in +[Usage & Logs](/agent-network/usage-and-logs); adjust them if your negotiated rates differ +from the catalog defaults. + +## The Keyless Endpoint + +All connected providers share a single account endpoint, generated when you connect your +first provider and reachable only over the NetBird overlay. + +

+ agent network endpoint on the Providers page +

+ +Agents send normal provider requests to the endpoint without an API key; which identities +may reach which providers is governed by [Policies](/agent-network/policies). + + diff --git a/src/pages/agent-network/quickstart.mdx b/src/pages/agent-network/quickstart.mdx new file mode 100644 index 00000000..7de42f39 --- /dev/null +++ b/src/pages/agent-network/quickstart.mdx @@ -0,0 +1,143 @@ +import { Note } from '@/components/mdx' + +export const description = + 'Get an LLM request routed through NetBird Agent Network end to end: set up the NetBird server with the proxy, connect a provider, create a policy, and make your first keyless call.' + +# NetBird Agent Network Quickstart + +This guide takes you from a fresh server to a working, keyless LLM call through +Agent Network. + + + NetBird Agent Network is open source and self-hosted, so you can run it on your own servers. This guide sets up a minimal + NetBird deployment with the core Agent Network functionality. You can enable the full platform later. + The code lives in the [netbirdio/netbird](https://github.com/netbirdio/netbird/agent-network) repository. + + +## Infrastructure Requirements + +- A Linux VM with at least **1 CPU** and **2 GB** of memory. +- The VM must be publicly accessible on **TCP ports 80 and 443**, and **UDP port 3478**. +- A **public domain** that resolves to the VM's public IP (e.g. `netbird.example.com`), + plus a **wildcard record** (e.g. `*.netbird.example.com`) so agent-network + endpoints resolve. + +The public domain is not used for the Agent Network itself. It is only used to establish network connectivity +and manage the platform. + +## Software Requirements + +- Docker with the docker-compose plugin v2 or higher ([Docker installation guide](https://docs.docker.com/engine/install/)) +- [jq](https://jqlang.github.io/jq/) — install with `sudo apt install jq` or `sudo yum install jq` +- [curl](https://curl.se/) — install with `sudo apt install curl` or `sudo yum install curl` + +### Installation script + +Download and run the installation script: + +```bash +curl -fsSL https://pkgs.netbird.io/getting-started.sh | NETBIRD_AGENT_NETWORK=true bash +``` + +Once the script finishes, open `https://netbird.example.com`, create your admin +account on the setup page, create an admin user, and log in. + +## Add Your Device to the Network + +Agent network endpoints are private and reachable only over the NetBird overlay network. +To access one, your agent’s device must run the NetBird client and be authenticated, keeping access keyless, authorized, +and protected by a peer-to-peer encrypted WireGuard tunnel. + +1. In the NetBird dashboard go to **Peers > User Devices**. +2. Click **Add Peer** and download the NetBird client app for your device. +3. Run the client app, click "Connect", and log in with your NetBird account when prompted + +

+ agent network connect +

+ +You should now see your device in the peers list in the NetBird dashboard. + +To access a provider via NetBird, you need to use an **agent network endpoint**, which is generated when you connect your +first provider. + +## Connect a Provider + +A **provider** is an upstream LLM service that NetBird routes requests to, such as +OpenAI, Anthropic, any AI gateway, or a local model served by Ollama +or vLLM. + +1. Go to **Agent Network > Providers** and click **Connect Provider**. +2. Select the provider, such as **Anthropic** if you use Claude Code. +3. Paste the provider’s API key. +4. _(Optional)_ Set a list of allowed models and a custom token price. +5. Save the provider. + +NetBird stores the provider API key server-side and returns a tunnel-only endpoint that agents use to reach it. +The key never lives on the client. + +See [Providers](/agent-network/providers) for more details. + +

+ agent network add provider +

+ +You should now see a newly-generated endpoint above the **Providers** table. + +

+ agent network endpoint +

+ +## Configure Your Agent + +Point your agent at the NetBird endpoint as its **base URL**. No provider API key +is needed on the client. NetBird authorizes each request against your policies and +injects the upstream provider key server-side. + +1. Next to your agent network endpoint, click **Agent Config**. +2. Pick the tab that matches your tool — Claude Code, Codex, OpenAI SDK, or cURL. The + dashboard pre-fills your endpoint for you. +3. Copy the snippet and apply it. Claude Code reads `~/.claude/settings.json` and Codex + reads `~/.codex/config.toml`. + +

+ agent network agent config +

+ +## Create a Policy + +By default, Agent Network denies every request. Nothing reaches a provider until a +policy explicitly allows it. A policy connects a **Source Group** (your users or +agent devices) to one or more **Providers**, and is where you attach optional token +and budget limits and guardrails. + +1. Go to **Team > Users** and add your user to a group, such as **Engineering**. +2. Go to **Agent Network > Policies** and click **Add Policy**. +3. Select the **Source Group** you want to authorize. +4. Choose the **Provider** that members of the group can access. +5. _(Optional)_ Set **token / budget limits** and attach **guardrails**. +6. Save the policy. + +

+ agent network add policy +

+ +With the policy in place, the agent you configured above can now reach the provider. +Run it as usual, or send a quick test request, using a model your provider allows: + +```bash +curl https:///v1/messages \ + --header "Content-Type: application/json" \ + --header "anthropic-version: 2023-06-01" \ + --data '{"model":"claude-opus-4-8","max_tokens":1024,"messages":[{"role":"user","content":"What is NetBird?"}]}' +``` + +## Verify in Usage & Logs + +Open **Usage & Logs** to confirm the request was +recorded with the caller identity, model, tokens, and cost. + +

+ agent network usage & logs +

\ No newline at end of file diff --git a/src/pages/agent-network/usage-and-logs/access-logs.mdx b/src/pages/agent-network/usage-and-logs/access-logs.mdx new file mode 100644 index 00000000..5365c30b --- /dev/null +++ b/src/pages/agent-network/usage-and-logs/access-logs.mdx @@ -0,0 +1,46 @@ +export const description = + 'The per-request Agent Network access log: caller identity, provider, model, tokens, cost, decision, and reason, with server-side filtering.' + +# Access Logs + +The access log is a per-request audit trail of agent-network traffic. Each entry +records the caller, provider and model, tokens and cost, the policy decision, +and the reason a request was allowed or denied. + +

+ agent network access logs table +

+ +## Columns + +- **Time** +- **User / Agent** — the resolved caller identity. +- **Auth Group** — the groups that authorized the request. +- **Provider** — resolved provider and model. +- **Tokens** — input and output. +- **Cost** +- **Status** and **Reason** — for denials, the mapped policy reason; for + allowed requests, a link to the policy that authorized it. + +## Filtering + +

+ agent network access log filters +

+ +Filter the log by: + +- **Date** — defaults to the last 14 days. +- **User** +- **Group** +- **Provider** +- **Model** +- **Path** — match requests whose path starts with a given prefix (e.g. `/v1/messages`). + +All filtering is applied server-side. + +## Availability + +Access logs are retained only when log collection is enabled for the account. +Usage and cost are still recorded when it's off — see +[Log Collection & Retention](/agent-network/usage-and-logs/log-collection). \ No newline at end of file diff --git a/src/pages/agent-network/usage-and-logs/index.mdx b/src/pages/agent-network/usage-and-logs/index.mdx new file mode 100644 index 00000000..7677f733 --- /dev/null +++ b/src/pages/agent-network/usage-and-logs/index.mdx @@ -0,0 +1,23 @@ +export const description = + 'Operate Agent Network: token and cost dashboards, per-request access logs, and log collection controls.' + +# Usage & Logs + +Once traffic flows, Agent Network gives you a per-request audit with real caller +identity, cost attribution, and token usage. + +## In This Section + +- [Usage Overview](/agent-network/usage-and-logs/usage-overview) — token and + cost trends over time. +- [Access Logs](/agent-network/usage-and-logs/access-logs) — per-request log + with server-side filtering. +- [Log Collection & Retention](/agent-network/usage-and-logs/log-collection) — + enable/disable logging, set retention, and control prompt capture. + +## Usage vs. Logs + +Token and cost **usage** is always collected, so dashboards and limits stay +accurate even if access-log collection is turned off. The full **access log** +(request detail and optional prompts) is retained according to your log +collection settings. \ No newline at end of file diff --git a/src/pages/agent-network/usage-and-logs/log-collection.mdx b/src/pages/agent-network/usage-and-logs/log-collection.mdx new file mode 100644 index 00000000..820c457c --- /dev/null +++ b/src/pages/agent-network/usage-and-logs/log-collection.mdx @@ -0,0 +1,36 @@ +import { Note } from '@/components/mdx' + +export const description = + 'Control whether Agent Network access logs are collected, how long they are retained, and whether prompts are captured.' + +# Log Collection & Retention + +Found under **Agent Network → Configuration → Log Collection**, these +account-level controls govern how much request detail is stored. + +

+ agent network log collection and retention configuration +

+ +## Enable Log Collection + +Persist a per-request [access log](/agent-network/usage-and-logs/access-logs) +for every agent-network request. On by default. + + + Token and cost usage is recorded regardless of this setting, so + [Usage Overview](/agent-network/usage-and-logs/usage-overview) and limits stay + accurate even when log collection is off. + + +## Retention Period + +Choose how long access logs are kept before they're automatically deleted +(7–90 days, or indefinite). A periodic sweep removes older entries. Usage +history is kept separately and isn't affected. + +## Enable Prompt Collection + +Capture prompt and completion bodies on logged requests. Prompt capture only +runs when this is on **and** a policy [guardrail](/agent-network/policies/guardrails) +also enables it. PII redaction can strip sensitive data before storage. \ No newline at end of file diff --git a/src/pages/agent-network/usage-and-logs/usage-overview.mdx b/src/pages/agent-network/usage-and-logs/usage-overview.mdx new file mode 100644 index 00000000..5e2562f5 --- /dev/null +++ b/src/pages/agent-network/usage-and-logs/usage-overview.mdx @@ -0,0 +1,34 @@ +export const description = + 'Token and cost usage for Agent Network aggregated over time, filterable by date, user, group, provider, and model.' + +# Usage Overview + +The Usage tab shows account consumption over time as a per-day chart with a +Tokens / Cost switch, plus a breakdown table. + +

+ agent network usage overview chart and table +

+ +## Filters + +Filter the view by: + +- **Date** — defaults to the last 14 days. +- **User** +- **Group** +- **Provider** +- **Model** + +Filters apply to both the chart and the table. + +## Tokens vs. Cost + +Switch between input/output token totals and estimated USD spend. Cost is +derived from the per-model pricing configured on each +[provider](/agent-network/providers). + +## Always Collected + +Usage is recorded on every request independently of access-log collection, so +this view stays complete even when logs are disabled. \ No newline at end of file