diff --git a/public/docs-static/img/agent-network/connect-agent/agent-network-connect-agent-no-providers.png b/public/docs-static/img/agent-network/connect-agent/agent-network-connect-agent-no-providers.png new file mode 100644 index 000000000..2f9cf1d5d Binary files /dev/null and b/public/docs-static/img/agent-network/connect-agent/agent-network-connect-agent-no-providers.png differ diff --git a/public/docs-static/img/agent-network/connect-agent/agent-network-connect-agent-providers-models.png b/public/docs-static/img/agent-network/connect-agent/agent-network-connect-agent-providers-models.png new file mode 100644 index 000000000..3844631d7 Binary files /dev/null and b/public/docs-static/img/agent-network/connect-agent/agent-network-connect-agent-providers-models.png differ diff --git a/public/docs-static/img/agent-network/connect-agent/agent-network-connect-agent-user-role.png b/public/docs-static/img/agent-network/connect-agent/agent-network-connect-agent-user-role.png new file mode 100644 index 000000000..f758cdced Binary files /dev/null and b/public/docs-static/img/agent-network/connect-agent/agent-network-connect-agent-user-role.png differ diff --git a/public/docs-static/img/agent-network/connect-agent/agent-network-connect-agent.png b/public/docs-static/img/agent-network/connect-agent/agent-network-connect-agent.png new file mode 100644 index 000000000..acefcd403 Binary files /dev/null and b/public/docs-static/img/agent-network/connect-agent/agent-network-connect-agent.png differ diff --git a/public/docs-static/img/agent-network/providers/agent-network-load-models.png b/public/docs-static/img/agent-network/providers/agent-network-load-models.png new file mode 100644 index 000000000..d8119a64a Binary files /dev/null and b/public/docs-static/img/agent-network/providers/agent-network-load-models.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 index 4175febff..59c8a2809 100644 Binary files a/public/docs-static/img/agent-network/providers/agent-network-providers-list.png 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 index c029ed72a..d578e4e5e 100644 Binary files a/public/docs-static/img/agent-network/quickstart/agent-network-add-policy.png 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-connect-agent.png b/public/docs-static/img/agent-network/quickstart/agent-network-connect-agent.png new file mode 100644 index 000000000..e7ad0408a Binary files /dev/null and b/public/docs-static/img/agent-network/quickstart/agent-network-connect-agent.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 index 6d8c805e9..6b9ff6da0 100644 Binary files a/public/docs-static/img/agent-network/quickstart/agent-network-endpoint.png and b/public/docs-static/img/agent-network/quickstart/agent-network-endpoint.png differ diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index a7cf7eef7..3240a5ea3 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -508,6 +508,10 @@ export const docsNavigation = [ { title: 'How It Works', href: '/agent-network/how-it-works' }, { title: 'Quickstart', href: '/agent-network/quickstart' }, { title: 'Providers', href: '/agent-network/providers' }, + { + title: 'Connect Agents', + href: '/agent-network/connect-agents', + }, { title: 'Clusters', href: '/agent-network/clusters' }, ], }, diff --git a/src/pages/agent-network/connect-agents.mdx b/src/pages/agent-network/connect-agents.mdx new file mode 100644 index 000000000..7b7925b54 --- /dev/null +++ b/src/pages/agent-network/connect-agents.mdx @@ -0,0 +1,108 @@ +import { Note } from '@/components/mdx' + +export const description = + 'Point a local AI tool at NetBird Agent Network from the Connect Agent page: the keyless endpoint, ready-made configuration for Claude Code, Codex, the OpenAI SDK and cURL, and the providers and models your own policies allow.' + +# Connect Agents + +**Connect Agents** is the self-service page each user configures their own tools from. It +carries the account's [keyless endpoint](/agent-network/providers#the-keyless-endpoint), a +ready-made configuration snippet for common agent tools, and the providers and models the +user's own policies allow. + +Unlike the rest of Agent Network, the page needs no administrative permission. Every +authenticated account member sees it, and the answer behind it is computed from the caller's +own group memberships, so two users on the same account can see different providers. + +

+ Connect Agent page with the API base URL, the Claude Code configuration snippet, and the caller's providers and models +

+ +## API Base URL + +The endpoint is the account's Agent Network base URL, shared by every connected provider +and reachable only over the NetBird overlay. + +Agents send ordinary LLM requests to it with no provider API key. NetBird +authenticates the caller through your identity provider, authorizes the request against +your [policies](/agent-network/policies), and injects the upstream provider key +server-side. + +## Configure Your Tool + +Pick the tab that matches your tool. Each snippet is pre-filled with your endpoint, so it +can be copied and applied as it is: + +- **Claude Code** — writes `ANTHROPIC_BASE_URL` into `~/.claude/settings.json`, together + with an `apiKeyHelper` that satisfies the client's key check without a real key. Use the + **Shell** link above the snippet to switch to the equivalent `export` lines, and **JSON** + to switch back. +- **Codex** — a provider block for `~/.codex/config.toml`. +- **OpenAI SDK** — a Python client pointed at the endpoint's `/v1` path, with a placeholder + `api_key` the client requires but NetBird ignores. +- **cURL** — a complete request, handy for a first smoke test. + +The dropdown above the Claude Code snippet selects which backend the configuration targets: +**Anthropic API**, **Vertex AI**, or **Bedrock**. Claude Code reaches Vertex AI and Bedrock +through their own base URL variables, so the snippet changes accordingly. + + +A **Kimi CLI** tab and a **Kimi (Moonshot AI)** entry in the Claude Code dropdown appear +only when a Kimi provider is reachable for you, since that configuration works only against +an endpoint that can route to it. See the +[Kimi integration guide](/agent-network/integrations/kimi) for the provider side. + + +## Your Providers & Models + +The table lists what the caller's policies authorize, not everything the account has +connected. Each row names the provider as the administrator labelled it, with the catalog +provider underneath, and the models it may be called with: + +- **All Models** — no [guardrail](/agent-network/policies/guardrails) model allowlist + restricts this provider for you. +- One or two model names, or a count such as **3 Models** past that — the effective + allowlist. Hover the count to read the full list. + +

+ Your Providers & Models table listing a Bedrock provider limited to three models and an OpenAI provider with all models allowed +

+ +A provider the account has connected but no policy of yours references does not appear +here, and a request to it is refused at the endpoint the same way. + +## No Providers Available Yet + +Agent Network denies every request by default, so a user no policy covers yet sees the +endpoint and the snippets but an empty provider list. + +

+ Connect Agent page with an empty provider list explaining that no access policy covers the user yet +

+ +The empty state states the fix in the terms of whoever is reading it: + +- Users who can edit policies are pointed straight at **Policies**, where adding one of + their groups to a policy grants them access. +- Everyone else is asked to have an administrator add them to an Agent Network access + policy. + +This is also what an account with no providers connected at all looks like from a member's +side: with nothing connected there is nothing for a policy to authorize. An administrator +starts by [connecting a provider](/agent-network/providers#connect-a-provider), then +[creating a policy](/agent-network/policies) that covers the group the user belongs to. The +page fills in as soon as both exist, no change is needed on the agent. + +## What a Regular User Sees + +A member with the plain **User** role gets the same page as an administrator: the same +endpoint, the same per-tool snippets, and the providers their own policies allow. Only the +sidebar differs, it carries **Connect Agent** and **Usage & Logs**, scoped to their own +requests, without Providers, Policies, or Configuration. + +

+ Connect Agent page as seen by a member with the User role, whose sidebar carries only Connect Agent and Usage & Logs under Agent Network +

+ +This is the page to point a new user at: nothing on it needs an administrator, and it always +shows what that user in particular may call. diff --git a/src/pages/agent-network/providers.mdx b/src/pages/agent-network/providers.mdx index a1e3b5e50..900a83ff1 100644 --- a/src/pages/agent-network/providers.mdx +++ b/src/pages/agent-network/providers.mdx @@ -136,6 +136,49 @@ Self-hosters can seed the catalog defaults these fields prefill from with a pricing file. See [`server.agentNetwork.pricingDefaultsFile`](/selfhosted/maintenance/configuration-files#agent-network-settings). +### Loading Models from the Provider + +The catalog ships the model line-up NetBird knew about when your version was built. It +cannot know what your credential is actually entitled to, and it drifts as vendors add +and retire models. **Load models from provider** on the **Models** tab closes that gap: it +asks the vendor which models this credential can reach and merges the answer into the model +picker. + +That matters differently per provider: + +- **AWS Bedrock** — some ids invoke a foundation model directly in your Region, such as + `anthropic.claude-sonnet-4-5-20250929-v1:0`, while others are cross-Region inference + profiles carrying a geography prefix like `eu.`, `us.`, or `global.`. Only the exact id + AWS issues works at invoke time, and which ids your credential can use depends on your + account and region, so a shipped catalog cannot know your line-up. +- **Google Vertex AI** — discovery returns the publisher's global model list; invoking a + listed model can still be rejected if the configured project does not have access to it. +- **OpenAI** and **Anthropic** — the public line-up is in the catalog, but an organization's + access is not: preview and early-access models never appear, and models retired since your + NetBird release still do. + +1. Open the **Models** tab while connecting a provider, or when editing a saved one. +2. Click **Load models from provider**. A provider you are still typing in needs its + endpoint URL and API key filled first; a saved provider reuses its stored credential + server-side, so the key never returns to the browser. +3. Pick what you need with **Add More**, which searches the catalog and the loaded models + together. + +

+ Models tab of the Connect Provider modal with the Load models from provider button +

+ +Loaded models arrive with the rates NetBird would bill them at, taken from the same table +the proxy meters with, so a prefilled row shows what a request actually costs. A model +NetBird has no rate for arrives at zero and is flagged: register it as it is and every +request to it records a cost of zero, so set its prices yourself. + + +Most gateways publish no model listing. For those the button reports that the provider has +no listing endpoint and the catalog list is used instead — the provider still works, and an +empty model list keeps it a catch-all that accepts any model. + + ### Adding a Model Not in the Catalog If the model you need isn't in the picker, type its model ID directly into the **Model** field diff --git a/src/pages/agent-network/quickstart.mdx b/src/pages/agent-network/quickstart.mdx index d588fcd86..9408c6a3f 100644 --- a/src/pages/agent-network/quickstart.mdx +++ b/src/pages/agent-network/quickstart.mdx @@ -95,16 +95,20 @@ Point your agent at the NetBird endpoint as its **base URL**. No provider API ke 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**. +1. Go to **Agent Network > Connect Agents**. Every account member has this page, and it + shows the endpoint along with the providers their own policies allow. 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`.

- NetBird Configure Your Agent modal showing Claude Code configuration + Connect Agent page showing the endpoint and the Claude Code configuration snippet

+See [Connect Agents](/agent-network/connect-agents) for the rest of the page, including +what each tab configures. + ## Create a Policy By default, Agent Network denies every request. Nothing reaches a provider until a @@ -120,7 +124,7 @@ and budget limits and guardrails. 6. Save the policy.

- agent network add policy + Create Agent Policy modal with a source group and a provider selected

With the policy in place, the agent you configured above can now reach the provider.