diff --git a/docs.json b/docs.json index 8f4bfdd..42324a7 100644 --- a/docs.json +++ b/docs.json @@ -56,6 +56,7 @@ "group": "Public Resources", "pages": [ "manage/resources/public/http-https", + "manage/resources/public/ai-gateway", "manage/resources/public/ssh", "manage/resources/public/rdp", "manage/resources/public/vnc", @@ -74,6 +75,7 @@ "manage/resources/private/host", "manage/resources/private/cidr", "manage/resources/private/private-http", + "manage/resources/private/ai-gateway", "manage/resources/private/ssh", "manage/resources/private/authentication", "manage/resources/private/destinations", diff --git a/manage/ai/overview.mdx b/manage/ai/overview.mdx index 6ee7dc3..36306d4 100644 --- a/manage/ai/overview.mdx +++ b/manage/ai/overview.mdx @@ -20,7 +20,7 @@ Create an org-level provider so the gateway has an upstream to call. Sidebar → ## 2. Create a Resource -Resources → **Create** → set **Type** to **AI Gateway**, pick a domain, and attach the provider(s) from step 1. You can also attach providers to an existing resource later from its **AI Gateway** settings tab. +Resources → **Create** → set **Type** to **AI Gateway**, pick a domain, and attach the provider(s) from step 1. You can also attach providers to an existing resource later from its **AI Gateway** settings tab. How public and private AI Gateway resources reach users is covered on the [public](/manage/resources/public/ai-gateway) and [private](/manage/resources/private/ai-gateway) resource type pages. ## 3. Get a Key diff --git a/manage/resources/private/ai-gateway.mdx b/manage/resources/private/ai-gateway.mdx new file mode 100644 index 0000000..2724f18 --- /dev/null +++ b/manage/resources/private/ai-gateway.mdx @@ -0,0 +1,39 @@ +--- +title: "AI Gateway" +description: "Reach an AI API over the Pangolin tunnel using the connected client's identity" +--- + +A private AI Gateway resource exposes an AI API only to devices connected with the [Pangolin client](/manage/clients/install-client). Nothing is reachable from the public internet. Unlike [public AI Gateway](/manage/resources/public/ai-gateway), the gateway does not check a virtual API key. Identity comes from the active client connection. + +This page covers how the **resource** works: reachability, access, and what you attach. Providers, model routing, the catalog, and client setup live in [AI Gateway](/manage/ai/overview). + +## How It Works + +1. You create a private resource with type **AI Gateway** on a Newt site and attach one or more org-level [providers](/manage/ai/providers/overview). +2. You grant [users, roles, or machines](/manage/resources/private/authentication) access, the same as any other private resource. +3. The user connects with the Pangolin client. The machine running the AI client must be on that tunnel. +4. The agent calls the resource URL. Pangolin attributes the call to the connected user and proxies to the selected provider. + +Clients still need a value in the API key field. Use the literal string `none`. Deleting the field usually breaks the client. + +## Providers, Not Destinations + +Private AI Gateway resources attach providers on the resource's **AI Gateway** tab. They do not use a host or CIDR [destination](/manage/resources/private/destinations) as the model backend. Cloud APIs are called from Pangolin. [Custom](/manage/ai/providers/custom) providers can use **Site Targets** when the model server is on a site network. + +Private resources, including this type, can only be created on [Newt sites](/manage/sites/understanding-sites#newt-site-recommended). + +## Authentication and Access Rules + +Access is the private resource model: grant users, roles, or machines explicitly. See [Private Authentication](/manage/resources/private/authentication). + +When the connected client maps to a user, Pangolin forwards that identity upstream as [`Remote-*` headers](/manage/ai/providers/configuration#identity-headers). + +## Compared to Public AI Gateway + +| | Private AI Gateway | [Public AI Gateway](/manage/resources/public/ai-gateway) | +|---|---|---| +| **Reachability** | Pangolin client tunnel | Public FQDN | +| **Auth** | Client identity; use `none` as the key placeholder | [Virtual API key](/manage/ai/virtual-api-keys) on every call | +| **Who can call it** | Users, roles, and machines granted on the resource | Identity keys follow users and roles; manual keys grant access when created | + +For providers, model routing, and connecting Claude Code, Codex, and other clients, see [AI Gateway](/manage/ai/overview). diff --git a/manage/resources/public/ai-gateway.mdx b/manage/resources/public/ai-gateway.mdx new file mode 100644 index 0000000..0a17e97 --- /dev/null +++ b/manage/resources/public/ai-gateway.mdx @@ -0,0 +1,45 @@ +--- +title: "AI Gateway" +description: "Publish an AI API on a public FQDN and authenticate coding agents with virtual API keys" +--- + +An AI Gateway public resource is a protocol-aware reverse proxy on a fully qualified domain name, like [HTTP / HTTPS](/manage/resources/public/http-https). Clients call that URL instead of OpenAI, Anthropic, Gemini, or another model API. Pangolin authenticates the caller, then forwards the request to an attached [provider](/manage/ai/providers/overview). + +This page covers how the **resource** works: reachability, authentication, and what you attach. Providers, keys, model routing, the catalog, and client setup live in [AI Gateway](/manage/ai/overview). + +## How It Works + +1. You assign a FQDN on a domain managed in Pangolin and set the resource type to **AI Gateway**. +2. You attach one or more org-level providers. The resource speaks the API formats those providers advertise. +3. A user retrieves a [virtual API key](/manage/ai/virtual-api-keys) by visiting the URL in a browser and logging in, or from the Resource Launcher or `https://app.pangolin.net//keys`. +4. Coding agents send that key to the same FQDN. Pangolin checks the key and proxies to the selected provider. + +Visiting the URL in a browser is how you retrieve a key. Model calls still need the key in the request. A dashboard session cookie cannot proxy through the gateway. + +## Providers, Not Targets + +AI Gateway public resources do **not** use HTTP [targets](/manage/resources/public/targets). Traffic goes to providers configured under **AI Gateway → Providers**, then attached on the resource. + +Cloud APIs (OpenAI, Anthropic, and similar) need no site. [Custom](/manage/ai/providers/custom) providers can use **Site Targets** when the model server sits on a site network. That routing is on the provider, not on the resource. + +## Authentication and Access Rules + +Authentication is always on. You cannot turn Platform SSO off the way you can on an HTTPS resource. + +Assign [users and roles](/manage/access-control/create-user) the same way as a public HTTPS resource. Those grants control who can use an **identity key**. [Manual keys](/manage/ai/virtual-api-keys#manual-keys) grant access as soon as you create them, regardless of users and roles on the resource. + +When the call uses an identity key, or a manual key attributed to a user, Pangolin forwards that identity upstream as [`Remote-*` headers](/manage/ai/providers/configuration#identity-headers). An unattributed manual key authenticates without sending them. + +HTTPS resources can add PIN, passcode, header auth, shareable links, or email OTP. AI clients authenticate programmatically, so this type uses virtual API keys instead of those methods. See [Virtual API Keys](/manage/ai/virtual-api-keys) and [public authentication](/manage/resources/public/authentication). + +You can still attach a [resource policy](/manage/resources/public/resource-policies) for users, roles, and access rules. + +## Compared to Private AI Gateway + +| | Public AI Gateway | [Private AI Gateway](/manage/resources/private/ai-gateway) | +|---|---|---| +| **Reachability** | Public FQDN | Pangolin client tunnel | +| **Auth** | Virtual API key on every call | Client identity; the gateway does not check a key | +| **Browser visit** | Shows the user's key after login | Not used to retrieve a key | + +For providers, keys, model routing, and connecting Claude Code, Codex, and other clients, see [AI Gateway](/manage/ai/overview). diff --git a/manage/resources/public/authentication.mdx b/manage/resources/public/authentication.mdx index 9544fbd..e472c79 100644 --- a/manage/resources/public/authentication.mdx +++ b/manage/resources/public/authentication.mdx @@ -6,6 +6,8 @@ Though public resources are public and accessible to via a web browser, admins c You can configure these settings directly on each resource or share them across multiple resources with a [resource policy](/manage/resources/public/resource-policies). A resource either uses an inline policy (no shared policy attached) or inherits a shared policy and can add resource-specific overrides on top. +[AI Gateway](/manage/resources/public/ai-gateway) public resources always require authentication. Coding agents use [virtual API keys](/manage/ai/virtual-api-keys) rather than PIN, passcode, or email OTP. Users and roles still apply to identity keys the same way they do for HTTPS. + When an unauthenticated user visits a resource in their web browser, they will be redirected to a Pangolin-controlled authentication page where they must complete authentication. ## User Login diff --git a/manage/resources/understanding-resources.mdx b/manage/resources/understanding-resources.mdx index 93c73a3..05f4018 100644 --- a/manage/resources/understanding-resources.mdx +++ b/manage/resources/understanding-resources.mdx @@ -33,7 +33,9 @@ Public resources create a public proxy on the Pangolin server. The protocol chan HTTP/HTTPS, SSH, RDP, and VNC are all **browser-based**. You assign a fully qualified domain name (FQDN) to each resource and users open it in a web browser—no client-side software is required. Pangolin authentication and access rules protect all of these types the same way. You can configure those rules inline on each resource or share them through a [resource policy](/manage/resources/public/resource-policies). -SSH, RDP, and VNC require a **Newt site**. HTTP/HTTPS and TCP/UDP resources can also run on local and basic WireGuard sites. +[AI Gateway](/manage/resources/public/ai-gateway) also gets a public FQDN, but coding agents call it as an API. Visiting the URL in a browser is how users retrieve a virtual API key, not how they run the workload. + +SSH, RDP, and VNC require a **Newt site**. HTTP/HTTPS, AI Gateway, and TCP/UDP resources can also run on local and basic WireGuard sites. TCP and UDP are the exception. They do not receive a FQDN. Instead, they bind to a port on the Pangolin server host and act as simple protocol-agnostic pipes to the downstream resource. Because they are not protocol-aware, they do not enforce Pangolin authentication or access rules. @@ -42,6 +44,10 @@ TCP and UDP are the exception. They do not receive a FQDN. Instead, they bind to Websites, APIs, and dashboards behind an authenticated reverse proxy. + + Public FQDN for coding agents. Authenticate with virtual API keys. + + Full terminal in the browser with password, key, or Pangolin identity (PAM). @@ -73,13 +79,13 @@ TCP and UDP are the exception. They do not receive a FQDN. Instead, they bind to - HTTP/HTTPS and TCP/UDP only. + HTTP/HTTPS, AI Gateway, and TCP/UDP only. SSH, RDP, and VNC are not supported. - HTTP/HTTPS and TCP/UDP only. + HTTP/HTTPS, AI Gateway, and TCP/UDP only. SSH, RDP, and VNC are not supported. @@ -102,6 +108,10 @@ Private resources require users to connect with the Pangolin client before any t Private reverse proxy with optional TLS termination at the site edge. + + AI API over the client tunnel. Identity from the connected client. + + Traditional terminal SSH over the tunnel via `pangolin ssh`.