Agent Network (#813)

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: [

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.
+
+<p>
+    <img src="/docs-static/img/agent-network/global-limits/agent-network-global-limits-list.png" alt="agent network global limits list" className="imagewrapper-big" />
+</p>
+
+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.
+
+<p>
+    <img src="/docs-static/img/agent-network/global-limits/agent-network-create-global-limit.png" alt="create global limit modal with token and budget caps" className="imagewrapper" />
+</p>

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.
+
+<p>
+    <img src="/docs-static/img/agent-network/how-it-works/agent-network-diagram-llm-apis.png" alt="agent network LLM request path through the NetBird proxy" className="imagewrapper-big" />
+</p>
+
+- **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.
+
+<p>
+    <img src="/docs-static/img/agent-network/how-it-works/agent-network-diagram-internal-resources.png"
+         alt="agent network internal resource request path through WireGuard overlay" className="imagewrapper-big" />
+</p>
+
+## 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.

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.
+
+<p>
+    <img src="/docs-static/img/agent-network/overview/agent-network-control-center-v2.png" alt="agent network" className="imagewrapper-big" />
+</p>
+
+<Note>
+  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.
+</Note>
+
+## 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.
+
+<p>
+    <img src="/docs-static/img/agent-network/overview/agent-network-llm-policy.png" alt="agent network llm policy" className="imagewrapper" />
+</p>
+
+### 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.
+
+<p>
+    <img src="/docs-static/img/agent-network/overview/agent-network-internal-resources-policy.png" alt="agent network llm policy" className="imagewrapper" />
+</p>
+
+## 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.

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.
+
+<p>
+    <img src="/docs-static/img/agent-network/integrations/agent-network-connect-anthropic.png" alt="connect Anthropic provider in NetBird Agent Network" className="imagewrapper" />
+</p>
+
+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.
+
+<p>
+    <img src="/docs-static/img/agent-network/integrations/agent-network-create-policy.png" alt="create a NetBird Agent Network policy authorizing Claude Code" className="imagewrapper" />
+</p>
+
+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://<your-endpoint>"
+  }
+}
+```
+
+## Configure with Shell Variables
+
+Alternatively, export the variables before launching Claude Code:
+
+```bash
+export ANTHROPIC_BASE_URL=https://<your-endpoint>
+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.
+
+<p>
+    <img src="/docs-static/img/agent-network/usage-and-logs/agent-network-access-logs.png" alt="NetBird Agent Network access logs showing per-request Claude Code identity, group, model, cost, and status" className="imagewrapper-big" />
+</p>

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.
+
+<p>
+    <img src="/docs-static/img/agent-network/integrations/agent-network-connect-openai.png" alt="connect OpenAI provider in NetBird Agent Network" className="imagewrapper" />
+</p>
+
+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.
+
+<p>
+    <img src="/docs-static/img/agent-network/integrations/agent-network-create-policy-codex.png" alt="create a NetBird Agent Network policy authorizing Codex" className="imagewrapper" />
+</p>
+
+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://<your-endpoint>/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).

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 `<your-endpoint>` 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.

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.
+
+<p>
+    <img src="/docs-static/img/agent-network/integrations/agent-network-connect-litellm.png" alt="connect a self-hosted LiteLLM Proxy provider in NetBird Agent Network" className="imagewrapper" />
+</p>
+
+## 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.
+
+<p>
+    <img src="/docs-static/img/agent-network/integrations/agent-network-create-policy-litellm.png" alt="create a NetBird Agent Network policy authorizing LiteLLM" className="imagewrapper" />
+</p>
+
+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.
+
+<Note>
+  The configured key must be a LiteLLM **virtual key** with `metadata.allow_client_tags: true`,
+  otherwise LiteLLM silently drops the forwarded tags.
+</Note>
+
+## 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**.
+
+<p>
+    <img src="/docs-static/img/agent-network/integrations/agent-network-litellm-tag-usage.png" alt="LiteLLM Tag Usage view showing spend for the Engineering group injected by NetBird" className="imagewrapper-big" />
+</p>
+
+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.
+
+<p>
+    <img src="/docs-static/img/agent-network/integrations/agent-network-litellm-tag-management.png" alt="LiteLLM Tag Management listing the groups passed from NetBird, including Engineering" className="imagewrapper-big" />
+</p>
+
+## 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.
+
+<p>
+    <img src="/docs-static/img/agent-network/integrations/agent-network-litellm-access-logs.png" alt="NetBird Access Logs showing LiteLLM Proxy requests with the Engineering auth group" className="imagewrapper-big" />
+</p>

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.
+
+<p>
+    <img src="/docs-static/img/agent-network/policies/agent-network-guardrails.png" alt="agent network guardrails on a policy" className="imagewrapper" />
+</p>
+
+## 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.

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.
+
+<p>
+    <img src="/docs-static/img/agent-network/policies/agent-network-create-policy.png" alt="agent network llm policy" className="imagewrapper" />
+</p>
+
+<Note>
+    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).
+</Note>
+
+## 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
+```
+
+<p>
+    <img src="/docs-static/img/agent-network/policies/agent-network-access-log.png" alt="agent network log" className="imagewrapper-big" />
+</p>
+
+## More
+
+- [Token & Budget Limits](/agent-network/policies/limits)
+- [Guardrails](/agent-network/policies/guardrails)

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.
+
+<p>
+    <img src="/docs-static/img/agent-network/policies/agent-network-policy-limits.png" alt="agent network token and budget limits on a policy" className="imagewrapper" />
+</p>
+
+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).

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.
+
+<p>
+    <img src="/docs-static/img/agent-network/providers/agent-network-providers-list.png" alt="agent network providers list" className="imagewrapper-big" />
+</p>
+
+## 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.
+
+<p>
+    <img src="/docs-static/img/agent-network/providers/agent-network-create-provider.png" alt="agent network connect provider modal" className="imagewrapper" />
+</p>
+
+## 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.
+
+<p>
+    <img src="/docs-static/img/agent-network/quickstart/agent-network-endpoint.png" alt="agent network endpoint on the Providers page" className="imagewrapper" />
+</p>
+
+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).
+
+

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.
+
+<Note>
+    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.
+</Note>
+
+## 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
+
+<p>
+    <img src="/docs-static/img/agent-network/quickstart/agent-network-connect-device.png" alt="agent network connect" className="imagewrapper-medium" />
+</p>
+
+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.
+
+<p>
+    <img src="/docs-static/img/agent-network/quickstart/agent-network-add-provider.png" alt="agent network add provider" className="imagewrapper" />
+</p>
+
+You should now see a newly-generated endpoint above the **Providers** table.
+
+<p>
+    <img src="/docs-static/img/agent-network/quickstart/agent-network-endpoint.png" alt="agent network endpoint" className="imagewrapper" />
+</p>
+
+## 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`.
+
+<p>
+    <img src="/docs-static/img/agent-network/quickstart/agent-network-agent-config.png" alt="agent network agent config" className="imagewrapper" />
+</p>
+
+## 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.
+
+<p>
+    <img src="/docs-static/img/agent-network/quickstart/agent-network-add-policy.png" alt="agent network add policy" className="imagewrapper" />
+</p>
+
+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://<your-endpoint>/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.
+
+<p>
+    <img src="/docs-static/img/agent-network/quickstart/agent-network-usage-and-logs.png" alt="agent network usage & logs"
+         className="imagewrapper-big" />
+</p>

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.
+
+<p>
+    <img src="/docs-static/img/agent-network/usage-and-logs/agent-network-access-logs.png" alt="agent network access logs table" className="imagewrapper-big" />
+</p>
+
+## 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
+
+<p>
+    <img src="/docs-static/img/agent-network/usage-and-logs/agent-network-access-log-filters.png" alt="agent network access log filters" className="imagewrapper-small" />
+</p>
+
+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).

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.

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.
+
+<p>
+    <img src="/docs-static/img/agent-network/usage-and-logs/agent-network-log-collection.png" alt="agent network log collection and retention configuration" className="imagewrapper-big" />
+</p>
+
+## Enable Log Collection
+
+Persist a per-request [access log](/agent-network/usage-and-logs/access-logs)
+for every agent-network request. On by default.
+
+<Note>
+  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.
+</Note>
+
+## 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.

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.
+
+<p>
+    <img src="/docs-static/img/agent-network/usage-and-logs/agent-network-usage-overview.png" alt="agent network usage overview chart and table" className="imagewrapper-big" />
+</p>
+
+## 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.