port mintlify to fumadocs

2026-10-14 16:49:09 +02:00 · 2026-09-25 15:31:51 -04:00
parent dc54fb1017
commit 63199a588c
373 changed files with 13533 additions and 4577 deletions
@@ -0,0 +1,43 @@
+---
+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 Pangolin 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 [Pangolin Sites](/manage/sites/understanding-sites#pangolin-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).
+
+## More Than One Resource
+
+Give different users and roles their own providers with more than one AI Gateway resource. Distinct hostnames are the usual approach. Unlike other private resource types, they can also share a FQDN because they all route to the gateway inside Pangolin. See [Multiple Gateway Resources](/manage/ai/multiple-gateway-resources).
+
+## 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).
@@ -0,0 +1,39 @@
+---
+title: "Aliases"
+description: "Friendly names for resources, overlaps, loopback on the site host, and DNS behavior"
+---
+Aliases provide a secondary, user-friendly address for any of your resources, allowing users to access the resource using this alternate name in addition to the original address.
+
+For instance, a router with the address `10.0.0.1` could be assigned the alias `router.internal`, and users could connect using either. Aliases are accessible to anyone who has access to the resource, and they are exclusively accessible when connected with a Pangolin client, meaning they function without requiring any external DNS record setup. Furthermore, aliases are protocol agnostic, which means they will work with any network protocol, essentially acting as a pseudo-A record for an address that is only functional within the Pangolin environment.
+
+## Overlapping Networks and Loopback on the Site Host
+
+Several situations described on the [Destinations](/manage/resources/private/destinations) page are where an alias is especially important—either optional but strongly recommended, or effectively required.
+
+Overlapping IP spaces across sites are common (for example the same RFC1918 subnet behind different Pangolin sites). Pangolin helps route connections without users picking a site by hand, but raw IPs or ambiguous names can still collide across environments. Assigning a distinct alias per resource gives clients a single hostname whose DNS resolution goes through Pangolin, so traffic consistently reaches the intended resource and site instead of whichever overlapping address would otherwise win. See [Overlapping destinations across sites](/manage/resources/private/destinations#overlapping-destinations-across-sites).
+
+Loopback on the site host is another case: if the resource destination is `127.0.0.1` or `localhost` on the machine running the site, those strings still mean “this machine” on the user’s laptop or desktop—not the remote site. There is no safe way for users to type loopback literals and reach the service behind another host; an alias hostname is required so the client resolves the name via Pangolin and sends traffic over the tunnel to the site, which then forwards to its own loopback. See [Loopback on the site host](/manage/resources/private/destinations#loopback-on-the-site-host).
+
+## CIDRs vs. IPs
+
+An alias can only be created for a resource that is a single host (IP or FQDN). Aliases cannot be created for resources that are CIDR ranges because it would be ambiguous which host within the range the alias should point to.
+
+## Domain Structure
+
+Since aliases cannot be single-label domains, you must avoid using domain names that do not contain a dot (e.g., `pangolin`). A domain like `pangolin.net`, which includes a dot, is acceptable. Instead of a single-label domain, you should consider using a subdomain of a domain you control, such as `router.mywebsite.com`, or an existing private/internal domain name, like `router.internal` or `router.corp`.
+
+### Wildcards
+
+Wildcards allow you to define aliases that match multiple hostnames using special characters in the FQDN. For example, in an alias like `*.host-0?.autoco.internal`, the asterisk `*` matches any sequence of characters (including none), and the question mark `?` matches exactly one character.
+
+If you use a wildcard such as `*.proxy.internal`, it will match any hostname that ends with `.proxy.internal` and has something before the dot—such as `host.proxy.internal`, `longerhost.proxy.internal`, or even `sub.host.proxy.internal`. However, the wildcard will not match the base domain itself (`autoco.internal` without anything before the dot).
+
+### .local TLD
+
+The `.local` TLD is reserved for local networking and multicast DNS (mDNS). mDNS is commonly used by Apple Bonjour, Linux zeroconf, and limited Windows features. Because of this, aliases that use `.local` may not resolve reliably across many devices. We recommend using a subdomain you control (for example, `alias.mywebsite.com`) or a private/internal domain such as `alias.internal` or `alias.corp`.
+
+## Custom Upstream DNS
+
+Aliases work by overriding the DNS of your computer running the client so that all DNS requests are sent to the Pangolin client for resolution. That behavior is controlled by the Enable Aliases (Override DNS) preference; see [Configure Clients](/manage/clients/configure-client#enable-aliases-override-dns). The DNS server on your computer is typically `100.96.128.1` (the first address inside of your utility subnet on the org) when connected to the tunnel, which forwards requests to an upstream server. By default, we use `1.1.1.1`, but this upstream address can be configured in the CLI or in the client settings.
+
+**If you are attempting to set an upstream DNS server that is only accessible via the tunnel, ensure that you create a resource and check the tunnel DNS option in the client configuration settings.** Otherwise, connectivity to the server may fail when connected to the tunnel. Enable Aliases (Override DNS) must also be on—see [Configure Clients](/manage/clients/configure-client#enable-aliases-override-dns)—so the client can intercept DNS and forward queries to the upstream server.
@@ -0,0 +1,13 @@
+---
+title: "Authentication"
+description: "Only allow access to resources to specific users, roles, and machines"
+---
+When a client connects into an organization they will NOT have access to any resources by default. Access must be explicitly granted to users, roles, or machines for a tunnel to be established to the site(s) hosting the resource. The client will show no sites or resources unless access is granted.
+
+Access can be granted in several ways:
+
+* **Roles:** Assign access to resources to specific roles. Any user with that role will gain access to the resource when they connect.
+* **Users:** Assign access to resources to specific users. Only those users will gain access to the resource when they connect.
+* **Machines:** Assign access to resources to specific machines. Only those machine clients will gain access to the resource when they connect. Note that machines can not be put into roles.
+
+When removing access to a resource, the client will automatically tear down the tunnel to that resource if there are no other resources accessible on that site.
@@ -0,0 +1,30 @@
+---
+title: "CIDR"
+description: "Route client traffic to an entire IP range on the remote network"
+---
+
+A CIDR private resource exposes an entire IP range on your remote network to connected Pangolin clients. When a user connects with the Pangolin client and has access to the resource, the client installs a route for that prefix and all traffic to addresses within the range is carried over the tunnel.
+
+CIDR resources are the usual choice for whole subnets or network segments instead of creating a separate host resource for every machine.
+
+## Destination
+
+A CIDR resource destination is an IP range in CIDR notation—for example `10.1.0.0/16`. Any address inside the range is covered for users who have been granted access.
+
+The site connector must have routable access to the entire prefix. Confirm from the site's network that it can reach hosts across the range before creating the resource.
+
+## Port Restrictions
+
+[Port restrictions](/manage/resources/private/port-restrictions) apply to the entire CIDR range. Use Custom mode to allow only specific ports (for example `443` for HTTPS workloads across the subnet) or Blocked to disable a protocol entirely.
+
+## Multi-Site Routing
+
+When the same CIDR is reachable from multiple site connectors, attach all applicable sites. Pangolin [routes through the best available path](/manage/resources/private/multi-site-routing) and fails over when a site goes offline.
+
+<Warning>
+Only attach sites that can actually reach the configured CIDR. Mixing sites on unrelated networks where some cannot reach the range leads to unpredictable routing.
+</Warning>
+
+## Overlapping Networks
+
+If the same IP range exists on multiple sites, Pangolin resolves the conflict automatically. CIDR resources cannot use [aliases](/manage/resources/private/alias)—aliases apply to individual hosts only. If you need predictable routing to a specific site, create separate [host resources](/manage/resources/private/host) for the machines you care about instead of relying on a shared CIDR range.
@@ -0,0 +1,63 @@
+---
+title: "Destinations"
+description: "What a private resource destination is and how to define it (FQDN, IP, or CIDR)"
+---
+
+## What is a destination?
+
+A destination is the network location your site can route to for a private resource: a single host IP address, an IP CIDR range, or a fully qualified domain name (FQDN). Every private resource must have a destination—it tells Pangolin where the resource lives on the remote network and how the site should reach it.
+
+When a user connects with the Pangolin client and has access to that resource, their traffic is steered toward the address or range defined by the destination.
+
+That role is similar to a [target](/manage/resources/public/targets) on a public resource: both tell Pangolin where to send traffic after it enters the platform. For public resources, traffic typically arrives from the internet; for private resources, it comes from other clients already connected to your organization.
+
+You can optionally add an [alias](/manage/resources/private/alias) so people use a memorable hostname instead of the raw destination, or so overlapping IPs across sites resolve predictably (see [Overlapping destinations across sites](#overlapping-destinations-across-sites) below). In some setups an alias is required—for example when the destination is loopback on the site host ([Loopback on the site host](#loopback-on-the-site-host)).
+
+## Defining a Destination
+
+A private resource destination is always exactly one of the following: a single host IP, a CIDR range, or a FQDN.
+
+### IP Address
+
+Use a single IP address for one host on the remote network—for example, `10.1.0.35`. The Pangolin client installs a route for that host when the user connects with access to the resource, and traffic to that IP is carried over the tunnel to the site, which delivers it on the remote network.
+
+### Loopback on the Site Host
+
+If the service lives on the same machine as the Pangolin site, you can set the destination to `127.0.0.1` or `localhost`. The site then routes to its own loopback interface, which is where that process is listening.
+
+On the user’s machine, `localhost` and `127.0.0.1` always mean that machine, not the remote site. Telling someone to open `http://127.0.0.1:8080` in a browser would hit their laptop, not the site.
+
+So you must add an [alias](/manage/resources/private/alias)—for example a hostname only resolvable through Pangolin, such as `metrics.site-internal.example`—and have people use that name to connect. The client resolves the alias via Pangolin, sends traffic over the tunnel, and the site forwards it to `127.0.0.1` / `localhost` on its side. This is an example where an alias is required and where it resolves overlapping or conflicting meanings of the same address between the client and the site.
+
+### CIDR Range
+
+Use an IP CIDR range when many addresses should be reachable as one resource—for example, `10.1.0.0/16`. Any address inside the range is covered for users who have been granted access. The client installs routing for that prefix when they connect. This is the usual choice for whole subnets or segments instead of listing hosts one by one.
+
+### FQDN
+
+Use a fully qualified domain name when the resource is identified by DNS on the remote network—for example, `host.autoco.internal`. The Pangolin site resolves that hostname to an IP address on the network behind the site. That is a good fit when the host’s address can change but the name stays the same.
+
+Another pattern is routing traffic destined for a public SaaS hostname through a Pangolin site using the client. For example, you can configure a private resource whose destination is `google.com`. When a user with access opens `google.com` in the browser, the client sends that traffic over the tunnel to the site. Because the site treats `google.com` as the resource’s destination, it proxies that traffic out to the internet from the site’s egress. The flow is: client → tunnel → site → upstream host, instead of the client reaching the host directly on its local path.
+
+### Additional Notes on Resource Destinations
+
+* Reserved IP Addresses: The Pangolin client reserves the CGNAT subnet 100.96.128.0/24. Accessing resources via an IP address within this reserved range will be blocked by the client, though its use is uncommon. This range can be configured for newly created orgs in the self-hosted Pangolin configuration file.
+* Resource Destination Resolution: The configured address of the Resource is resolved by the site the resource points to. Make sure the site can resolve the address correctly.
+
+### Overlapping destinations across sites
+
+Pangolin smooths away overlapping networks and arbitrarily chooses a single site to resolve the IP address or range to. This is because we want connection requests to any Resource to be as simple as possible for the end users: when they connect to a particular IP address or FQDN, Pangolin figures out which site to send it to and the end user never needs to figure this out.
+
+It is recommended that you create overlapping resources only if absolutely required. If you do, use [Aliases](/manage/resources/private/alias) to explicitly define which host should be used for a given FQDN or IP address and use the alias to connect.
+
+### Overlapping destinations with local routes
+
+The Pangolin client uses split tunneling: it only routes traffic for the private resources you've defined, and leaves everything else—public websites, local printers, other network devices—on the device's normal network path.
+
+If a resource's destination overlaps with the user's local subnet, the client can end up capturing traffic that should have stayed local. For example, if a resource is defined as `192.168.1.0/24` (or a specific IP inside that range) and the user's home network is also on `192.168.1.0/24`, the client will route their local traffic—like printer or NAS access—over the tunnel instead, where it fails.
+
+**Symptoms** include a user losing access to a local printer, file server, or another VPN client once connected to Pangolin.
+
+**To fix it**, have the user check their local IP and subnet (`ipconfig` on Windows, `ifconfig`/`ip addr` on macOS/Linux), then compare it against your resource destinations. The recommended solution is to use more specific routes for your resources to prevent routing conflicts. For example instead of using a whole CIDR, use only host resources, or use more specific CIDRs like a /30 instead of a /24. Clients will always route to more specific routes over less specific ones. This way resource access is still controlled by Pangolin while the user's local and internet traffic is undisturbed.
+
+If the above does not work, on Windows and Linux you can update the Pangolin client configuration to add a `prefer local routes` entry for the user's local subnet. This will tell the client to leave that traffic on the local network instead of routing it over the tunnel. See the [Configure Clients](/manage/clients/configure-client) page.
@@ -0,0 +1,34 @@
+---
+title: "Host"
+description: "Route client traffic to a single IP address or FQDN on the remote network"
+---
+
+A host private resource exposes a single machine on your remote network to connected Pangolin clients. When a user connects with the Pangolin client and has access to the resource, traffic destined for that host is carried over the tunnel to the site, which delivers it on the remote network.
+
+Host resources are the most common private resource type. They do not render in a browser—you use native applications (a database client, `curl`, an RDP client, etc.) against the destination address while the Pangolin client is connected.
+
+## Destination
+
+Every host resource has a [destination](/manage/resources/private/destinations): a single IP address or fully qualified domain name (FQDN).
+
+| Destination type | Example | When to use |
+|------------------|---------|-------------|
+| IP address | `10.1.0.35` | A host with a stable IP on the remote network |
+| FQDN | `db.autoco.internal` | A host identified by DNS that may change IP |
+| Loopback | `127.0.0.1` | A service running on the site connector host itself |
+
+### Loopback on the Site Host
+
+If the service runs on the same machine as the site connector, set the destination to `127.0.0.1` or `localhost`. On the user's machine, `localhost` always refers to their own computer—not the remote site. You must add an [alias](/manage/resources/private/alias) (for example `metrics.site-internal.example`) so users connect to a name that Pangolin resolves over the tunnel.
+
+## Port Restrictions
+
+By default, all TCP and UDP ports on the destination are reachable. Tighten access with [port restrictions](/manage/resources/private/port-restrictions) to allow only the ports your application needs.
+
+## Multi-Site Routing
+
+Attach multiple sites to a host resource when the same destination is reachable from more than one connector. Pangolin [routes traffic through the best available site](/manage/resources/private/multi-site-routing) and fails over automatically when a site goes offline.
+
+## Aliases
+
+Optionally assign an [alias](/manage/resources/private/alias) so users connect with a memorable hostname instead of a raw IP. Aliases are required for loopback destinations and recommended when the same IP exists on overlapping networks across sites.
@@ -0,0 +1,27 @@
+---
+title: "Multi-site Routing and High Availability"
+description: "Use multiple sites on a private resource for resilient routing and failover"
+---
+When you configure a private resource, you can attach more than one site. Pangolin then chooses how to reach the resource’s destination through those sites, similar in spirit to running multiple connectors into the same network: traffic is steered toward whichever path is most suitable at the time.
+
+### How Routing Works
+
+Pangolin evaluates the sites you selected and routes client traffic through the site that is most ideal from the client’s perspective. That decision weighs factors such as latency and whether the site is reachable. If a site becomes unavailable, clients begin using the next best online site without you having to reconfigure the resource.
+
+<Note>
+Failover may take a few seconds. The site must be registered as offline, routing changes propagated to clients, and only then can failover take effect, so a short gap while that happens is expected.
+</Note>
+
+You are not limited to two sites. You can select as many sites as you need on a single private resource, as long as every selected site can actually reach the resource’s destination on the network.
+
+### Example: Redundant Office Connectors
+
+Suppose your office LAN is reachable from two servers, and you install a Pangolin site connector on each. Both sites act as connectors into the same office network, so either site can route to the same internal hosts.
+
+You create one private resource for an internal service and select both sites. While both connectors are healthy, Pangolin sends traffic through the better path. If one server or connector goes down, clients keep access to the private resource because traffic fails over to the other online site.
+
+### Requirements and Pitfalls
+
+Every site you attach must have routable access to the resource destination (same logical network, correct routes, DNS or IP resolution from that site’s perspective, and so on). The product assumes that any site in the list is a valid path to the same destination.
+
+If you mix sites that live on entirely different networks and one or more of them cannot reach the destination, behavior becomes unpredictable and the resource may not work reliably. Before adding a site, confirm from that site’s network that it can reach the configured destination the same way you expect the primary site to.
@@ -0,0 +1,41 @@
+---
+title: "Ports and ICMP"
+description: "Configure TCP and UDP port modes and ICMP (ping) for private resources"
+---
+
+For each private resource, TCP and UDP are configured separately. Each protocol uses one of three modes: All, Blocked, or Custom. ICMP (ping) is controlled on its own and does not follow those TCP/UDP modes.
+
+## Port restrictions
+
+Port settings apply to users, roles, and machines that have access to the resource. They limit which application traffic can reach the resource’s destination through Pangolin.
+
+### All
+
+All means no port filtering for that protocol: every port on the destination is reachable through the tunnel. This is the default-style behavior when you are not narrowing traffic to a subset of ports.
+
+Use All when the service needs arbitrary ports (for example ephemeral ports on the client side are handled by the stack, but the server listens on many ports) or when you have not yet tightened access.
+
+### Blocked
+
+Blocked means that protocol is not allowed to the destination through Pangolin: no TCP or no UDP traffic passes, depending on which row you set. The other protocol can still be All or Custom independently-for example TCP Custom (only `443`) with UDP Blocked for a HTTPS-only workload that should not receive UDP to that destination.
+
+Use Blocked when you want to turn off a protocol entirely for that resource.
+
+### Custom
+
+Custom means only the ports you list are allowed; every other port for that protocol is denied. Enter either:
+
+* a single port (e.g. `80`),
+* a comma-separated list (e.g. `80,443,8080`), or
+* a range with a hyphen (e.g. `8000-8100`).
+* lists and ranges (e.g. `80,443,8080-8090,9000-9010`)
+
+Use Custom for least-privilege access: allow only the ports your application actually needs (see also [SSH](/manage/ssh) for allowing TCP `22` when using Pangolin SSH).
+
+## ICMP
+
+By default, ICMP (ping) to the resource’s destination is enabled. To turn it off, disable the ICMP option when configuring access to the resource. That stops ICMP echo requests (ping) to the destination for principals that have access.
+
+<Note>
+ICMP ping does not work when using a resource [alias](/manage/resources/private/alias) as the target-ping applies to the resource’s configured destination (FQDN, IP, or CIDR), not to alias hostnames.
+</Note>
@@ -0,0 +1,30 @@
+---
+title: "HTTP / HTTPS"
+description: "Private reverse proxy with optional TLS termination at the site edge over the Pangolin tunnel"
+---
+
+Private HTTP/HTTPS resources expose web applications over the Pangolin tunnel with a fully qualified domain name. Unlike [public HTTP/HTTPS resources](/manage/resources/public/http-https), nothing is reachable from the public internet—a user must connect with the Pangolin client first.
+
+Once connected, users open the resource in a normal web browser at a URL like `https://my-app.internal.example.com`. The Pangolin client resolves the hostname privately, traffic travels over the peer-to-peer tunnel, and the site connector terminates TLS and runs a reverse proxy to the backend.
+
+For a deep dive into how private HTTPS reverse proxying works—including DNS hijacking, overlay addressing, certificate push, and the embedded edge proxy—see [Building a Peer-to-Peer Alternative to Cloudflare Tunnels](https://pangolin.net/news/building-a-peer-to-edge-peer-reverse-proxy).
+
+## Hostname, DNS, and TLS
+
+When you create a private HTTP/HTTPS resource, you assign a domain name. That hostname must be a domain you have already added and configured in Pangolin (see [Domains](/manage/domains)). This is analogous to an [alias](/manage/resources/private/alias) in that the client resolves the name through Pangolin and traffic is steered to the correct site, but it is not the same system: the name must be a real domain managed in your organization, not an arbitrary internal alias.
+
+Enable SSL on the resource so Pangolin obtains and serves a valid certificate for that hostname. When a connected user opens the site in a browser, a reverse proxy running on the site terminates TLS and proxies the request downstream to your [destination](/manage/resources/private/destinations). The Pangolin control plane provisions routing and pushes certificates to the site connector, so users get normal HTTPS without certificate warnings.
+
+## Destination Fields
+
+The destination block for a private HTTP resource is closer to a [target](/manage/resources/public/targets) on a public resource than to a plain private resource: in addition to the upstream hostname or IP, you set a destination port and a scheme (`http` or `https`). Those values are required so the site knows how to open the connection to the backend after TLS is terminated at the proxy.
+
+## Compared to an IP Resource and an Alias
+
+You can approximate private browsing with a standard private resource by pairing an IP or internal hostname with an [alias](/manage/resources/private/alias) and a port. In practice you would still visit something like `https://your-alias.example:8443/` (or HTTP without a trusted name), and the browser will not show a normal publicly trusted certificate for that pattern the way it does for a first-class HTTPS hostname. Private HTTP is meant for the case where you want a real FQDN on your Pangolin domain with valid TLS and default ports, similar to a public resource, while keeping the surface client-only.
+
+## Compared to a Public Resource
+
+A [public resource](/manage/resources/public/authentication) is reachable from the internet; Pangolin sits in front with authentication (for example platform SSO or other methods) so unauthenticated requests are blocked at the edge—the “bouncer” in front of a public site.
+
+Private HTTP does not use that public forward-auth model for reachability. The hostname does not grant access from the open internet at all. The user must connect with the Pangolin client first, like a VPN, before the domain resolves and the reverse proxy will serve the app. Instead of a login page at the edge, Pangolin uses the user's active client connection to determine their identity and enforces [private resource access rules](/manage/resources/private/authentication) (users, roles, machines) from that session. The network path is client-attached only.
@@ -0,0 +1,62 @@
+---
+title: "SSH"
+description: "Connect to remote hosts over the Pangolin tunnel using the Pangolin CLI"
+---
+
+Private SSH resources let users connect to remote hosts from their terminal over the Pangolin tunnel. Unlike [public SSH resources](/manage/resources/public/ssh), private SSH is **not** browser-rendered.
+
+## How It Works
+
+1. The user connects with the Pangolin client (GUI or CLI).
+2. They run `pangolin ssh <alias>` where the alias matches the private resource.
+3. Pangolin checks the user's identity from the active client connection and enforces [private resource access rules](/manage/resources/private/authentication) (users, roles, machines).
+4. Depending on the SSH [configuration](/manage/ssh#configuration-options), Pangolin generates a short-lived certificate and provisions the user on the host, or the user authenticates with existing host credentials.
+5. An SSH session opens through the tunnel.
+
+The Pangolin client provides the tunnel; the CLI handles certificate generation, user provisioning, and the SSH session itself. No manual SSH key distribution is required when using automated provisioning.
+
+```bash
+pangolin ssh <resource-alias>
+```
+
+The tunnel can be provided by the CLI or by another Pangolin client (for example the macOS app). You can run the GUI for the tunnel and use the CLI only for SSH.
+
+## Destination and Access
+
+Create a private resource with a [destination](/manage/resources/private/destinations) (IP or FQDN) for the host you want to SSH into. Assign an [alias](/manage/resources/private/alias) so users have a friendly name to pass to `pangolin ssh`.
+
+Grant access to users or roles and ensure **TCP 22** is allowed in [port restrictions](/manage/resources/private/port-restrictions).
+
+<Warning>
+If TCP 22 is not allowed in the resource's port restrictions, users will not be able to establish SSH sessions to that resource even when the rest of the setup is correct.
+</Warning>
+
+## Site and Host Configuration
+
+SSH private resources do **not** use discrete targets. Instead, you:
+
+1. Select which sites can route to the resource.
+2. Enter the backend host and port—unless you selected **Pangolin SSH** mode, which executes sessions on the site connector host and does not require a host or port.
+
+<Warning>
+**Pangolin SSH mode requires root.** The Pangolin Site must run as root on the site connector host. Use `sudo pangolin up site ...` or run the site service as root. See [Install Sites](/manage/sites/install-site).
+</Warning>
+
+Pangolin routes through the site that is online and healthiest. See [Multi-site Routing](/manage/resources/private/multi-site-routing).
+
+## SSH Configuration
+
+The SSH settings on a private resource use the same options as [public SSH resources](/manage/resources/public/ssh). Mode, authentication method, and auth daemon location are configured identically in the dashboard.
+
+See [SSH Access](/manage/ssh) for a full explanation of each option, setup instructions, and an example for every configuration combination.
+
+## How Private SSH Differs from Public SSH
+
+| | Private SSH | [Public SSH](/manage/resources/public/ssh) |
+|---|-------------|--------------------------------------------|
+| **Access** | Pangolin CLI: `pangolin ssh <alias>` | Web browser at a public FQDN |
+| **Client required** | Yes — user must be connected with the Pangolin client | No |
+| **Auth layer** | Identity from the active client connection; [private resource access rules](/manage/resources/private/authentication) | [Public resource authentication](/manage/resources/public/authentication) — login page, SSO, access rules |
+| **Manual auth step** | Credentials handled by the SSH client or certificate flow | Username/password or private key entered in a browser form after the public auth layer |
+| **Hostname** | [Alias](/manage/resources/private/alias) on the private resource | Public FQDN on your Pangolin domain |
+| **Port restrictions** | TCP 22 must be allowed in [port restrictions](/manage/resources/private/port-restrictions) | Not applicable |