Add use benefits, use cases, and how to on each section

2026-10-21 12:09:07 +02:00 · 2026-10-12 16:14:47 -04:00
parent b3f8679cc4
commit 0e35e64892
20 changed files with 349 additions and 4 deletions
@@ -20,6 +20,25 @@ All approvals can also be managed from a central page as they stream in to allow
  <img src="/images/approvals_page.png" alt="Approvals page listing pending devices in the Pangolin dashboard" />
 </Frame>

+## Benefits
+
+- Stolen or phished credentials aren't enough to connect from an unknown device.
+- Admins see every new device before it can reach resources.
+- Approvals are set per role, so you can require them for some groups and not others.
+
+## Use Cases
+
+- Only allow company-issued laptops to connect, not personal devices.
+- Require approval for contractor roles while employees connect freely.
+- Catch an unexpected new device on a user's account before it reaches sensitive resources.
+
+## How Device Approvals Work
+
+1. A user in a role that requires approval connects a device for the first time.
+2. The device shows as Pending Approval and can't reach any organization resources.
+3. An admin approves or denies it from the device or the approvals page.
+4. Once approved, the device connects normally. Devices that were already approved aren't asked again.
+
 ## Enabling Device Approvals

 Device approvals are enabled on a per-role basis. To enable device approvals for a role, follow these steps:
@@ -9,6 +9,31 @@ Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [En

 Alert rules let you react to changes in Pangolin: you pick a source (what to watch), a trigger (which change matters), and one or more actions (what to do). For example, when a site moves from online to offline, email your admins and support; when a [health check](/manage/alerting/health-checks) or resource becomes unhealthy, call a webhook so a tool like Zapier can fan out the event.

+## Benefits
+
+- Find out about outages as they happen instead of from users.
+- Send alerts where your team already works: email, webhooks, or PagerDuty, Opsgenie, ServiceNow, and incident.io.
+- One rule can watch every site or resource, or only the ones you pick.
+- Health checks run from your sites, so alerts reflect what is reachable on the remote network.
+
+## Use cases
+
+- Page on-call when a production site goes offline.
+- Email a branch office's IT contact when their site connector drops.
+- Open an incident when a public resource's targets all become unhealthy.
+- Watch printers, cameras, or legacy servers with arbitrary health checks and alert when they stop responding.
+- Send events to a webhook to post in chat or trigger automation.
+
+## How alert rules work
+
+Each rule has three parts:
+
+1. A source: the sites, resources, or health checks to watch.
+2. A trigger: the state change that matters, such as going offline or becoming unhealthy.
+3. One or more actions: what Pangolin does when the trigger fires.
+
+When a watched entity changes state and matches the trigger, Pangolin runs every action on the rule.
+
 ## Where to create rules

 Create and manage rules from the Alert rules page under Alerting for your organization.
@@ -5,11 +5,23 @@ description: "Define Pangolin resources and site settings declaratively with YAM

 Blueprints let you define Pangolin resources as code. Instead of configuring every site, target, and access rule manually in the dashboard, you describe the desired state in YAML or container labels and let Pangolin apply it consistently.

-Use blueprints when you want:
+## Benefits

- Repeatable rollouts across many sites
- Version control for infrastructure and access settings
- A source of truth that can be reviewed, templated, and automated
+- Roll out the same resources and access settings across many sites without repeating dashboard work.
+- Keep infrastructure and access settings in version control, where changes can be reviewed and rolled back.
+- Template and automate configuration from CI, scripts, or provisioning tools.
+- Keep a resource's definition next to the container it exposes with container labels.
+
+## Use Cases
+
+- Stamp out an identical set of resources for every store, branch office, or customer site.
+- Manage Pangolin resources through pull requests in a GitOps workflow.
+- Define resources next to the Docker Compose services they expose, using container labels.
+- Bootstrap new sites with their resources during provisioning.
+
+## How Blueprints Work
+
+You describe the desired state in YAML or container labels and apply it through the dashboard, a site, the API, or the CLI. Pangolin matches each entry to an existing site, resource, or policy by its key and creates or updates it to match. A blueprint applied from a site file or container labels acts as an ongoing source of truth, while dashboard, API, and CLI applies are one-off. See [How YAML Blueprints Are Applied](#how-yaml-blueprints-are-applied).

 <Note type="info">
 Some features in this documentation are marked with **(EE)**, which means they require [Enterprise Edition](/self-host/enterprise-edition).
@@ -7,6 +7,21 @@ A private AI Gateway resource exposes an AI API only to devices connected with t

 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).

+## Benefits
+
+- The gateway is never reachable from the public internet, only from connected clients with access.
+- There are no API keys to issue or leak. The client connection identifies the caller.
+- Provider API keys stay in Pangolin and never reach users' machines.
+- Calls are attributed to the connected user, so [usage analytics](/manage/ai/usage-analytics) and [session logs](/manage/ai/session-logs) show who made each one.
+- Self-hosted model servers on a site network can sit behind the same gateway as cloud providers.
+
+## Use Cases
+
+- Give employees Claude Code, Codex, or other coding agents through company provider accounts without handing out provider keys.
+- Keep AI access limited to managed devices that run the Pangolin client.
+- Serve a self-hosted model, such as one running on Ollama or vLLM, to your team without exposing it to the internet.
+- Give machine clients, such as CI jobs or internal agents, model access tied to their own identity.
+
 ## 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).
@@ -7,6 +7,28 @@ A CIDR private resource exposes an entire IP range on your remote network to con

 CIDR resources are the usual choice for whole subnets or network segments instead of creating a separate host resource for every machine.

+## Benefits
+
+- One resource covers a whole subnet, so you don't have to create a resource for every machine.
+- Hosts added to the range later are reachable right away, with no change in Pangolin.
+- Access is still granted per user, role, or machine client, and port restrictions apply to the whole range.
+- Attaching several sites that reach the same range gives redundant paths with automatic failover.
+- CIDR resources are the building block for [subnet routers](/manage/clients/subnet-router), which give devices that can't run the client access to Pangolin resources.
+
+## Use Cases
+
+- Give IT or operations staff access to a full office or data center LAN.
+- Reach a cloud VPC, such as an AWS VPC or Azure VNet, through a site running inside it.
+- Manage a range of network equipment, IP cameras, or industrial devices on a dedicated subnet.
+- Let a team reach a lab or staging network where machines change often.
+- Restrict a range to a single protocol, such as HTTPS on port `443`, across every host in it.
+
+## How CIDR Resources Work
+
+When a user with access connects, the Pangolin client installs a route for the whole prefix. Any traffic to an address in that range goes over the encrypted tunnel to a site attached to the resource, and the site forwards it to the matching host on its network.
+
+The client only routes the prefixes a user has access to, so traffic to other addresses, including the public internet, stays on the device's normal network path. When a host resource and a CIDR resource overlap, the client prefers the more specific route.
+
 ## 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.
@@ -7,6 +7,28 @@ A host private resource exposes a single machine on your remote network to conne

 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.

+## Benefits
+
+- Nothing is exposed to the public internet. The host is only reachable by clients that are connected and granted access.
+- Access is scoped to a single machine, not the whole network behind the site, so users only reach what they need.
+- Any TCP or UDP protocol works, and you can narrow it to specific ports with port restrictions.
+- An alias gives users a stable, memorable name for the host without any external DNS records.
+- Attaching several sites gives the host redundant paths with automatic failover.
+
+## Use Cases
+
+- Connect to a database such as PostgreSQL or MySQL with your usual client, without opening its port to the internet.
+- Reach an internal API, admin panel, or dashboard from a laptop on any network.
+- Use a native RDP, SSH, or VNC client against a single server.
+- Reach a service that only listens on the site host's loopback interface, through an alias.
+- Give a machine client, such as a CI runner, access to one build server or artifact store.
+
+## How Host Resources Work
+
+When a user with access connects, the Pangolin client starts routing traffic for the host over the encrypted tunnel. That covers the destination address and, if the resource has one, its alias, which the client resolves through Pangolin. A site attached to the resource receives the traffic and sends it to the destination on its local network. Responses come back the same way.
+
+The site resolves the destination, so an FQDN only needs to resolve from the site's network, not from the user's device. Traffic to any other address stays on the user's normal network path, since the client only routes resources the user has access to.
+
 ## Destination

 Every host resource has a [destination](/manage/resources/private/destinations): a single IP address or fully qualified domain name (FQDN).
@@ -4,6 +4,19 @@ description: "Use multiple sites on a private resource for resilient routing and
 ---
 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.

+### Benefits
+
+- A single site or connector host going down doesn't cut users off from the resource.
+- Clients route through the best online site, weighing factors such as latency, so users never choose a site by hand.
+- Failover is automatic. You don't need to edit the resource or reconnect clients.
+- You can attach as many sites as you need to one resource.
+
+### Use Cases
+
+- Run two connectors into the same office LAN so access survives a server reboot or hardware failure.
+- Reach a cloud VPC through connectors in different availability zones.
+- Do maintenance or upgrades on one connector while users keep working through another.
+
 ### 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.
@@ -7,6 +7,28 @@ Private HTTP/HTTPS resources expose web applications over the Pangolin tunnel wi

 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.

+## Benefits
+
+- Web apps get a real hostname on your domain and a valid TLS certificate, so browsers show no certificate warnings.
+- Users browse on the default port with a clean URL, with no port numbers or IP addresses to remember.
+- Nothing is reachable from the public internet. The hostname only resolves for connected clients with access.
+- Identity comes from the client connection, so users don't see an extra login page in front of the app.
+- Traffic travels peer-to-peer from the client to the site, and TLS terminates at the site, close to the app.
+
+## Use Cases
+
+- Publish internal tools such as wikis, Grafana, or admin panels only to employees on the Pangolin client.
+- Serve a self-hosted app over HTTPS when it only speaks plain HTTP on the local network.
+- Replace a public resource for sensitive apps that should never have a public login page.
+- Give contractors browser access to a staging site without exposing it to the internet.
+
+## How Private HTTP Resources Work
+
+1. You assign a hostname on a domain configured in Pangolin and set the destination host, port, and scheme.
+2. The Pangolin control plane provisions routing and pushes a certificate for that hostname to the site.
+3. A connected user with access opens the URL. The Pangolin client resolves the hostname privately and sends the request over the tunnel to the site.
+4. A reverse proxy on the site terminates TLS and proxies the request to the destination.
+
 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
@@ -5,6 +5,21 @@ description: "Connect to remote hosts over the Pangolin tunnel using the Pangoli

 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.

+## Benefits
+
+- SSH servers are never exposed to the public internet. Only connected clients with access can reach them.
+- With automated provisioning, users sign in with their Pangolin identity and get short-lived certificates, so there are no long-lived keys to distribute or rotate.
+- Accounts are created on the host just in time, with sudo and group permissions set by role.
+- Users keep a native terminal workflow, including their own shell, tools, and SSH options.
+- Removing a user's access in Pangolin cuts off their path to the host, whatever credentials they still hold.
+
+## Use Cases
+
+- Give engineers SSH access to production or staging servers based on their role.
+- Reach many servers behind one bastion, with an auth daemon provisioning users on each host.
+- Replace a shared jump host and hand-managed `authorized_keys` files.
+- Let on-call staff get into servers from anywhere without a separate VPN.
+
 ## How It Works

 1. The user connects with the Pangolin client (GUI or CLI).
@@ -7,6 +7,20 @@ An AI Gateway public resource is a protocol-aware reverse proxy on a fully quali

 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).

+## Benefits
+
+- Coding agents work from anywhere, with no Pangolin client on the device.
+- Provider API keys stay in Pangolin. Users get virtual API keys that you can revoke without rotating the provider key.
+- Identity keys follow user and role grants, so removing someone's access disables their key.
+- One URL can front several providers, with model routing, budgets, and usage analytics in one place.
+
+## Use Cases
+
+- Give a team Claude Code, Codex, or Gemini CLI on company provider accounts.
+- Issue manual keys to CI pipelines, scripts, or internal services that call a model API.
+- Track AI usage per user and key, and cap spend by role, key, or model with [budgets](/manage/ai/budgets).
+- Limit which models each team can use with [model routing](/manage/ai/providers/model-routing).
+
 ## How It Works

 1. You assign a FQDN on a domain managed in Pangolin and set the resource type to **AI Gateway**.
@@ -5,6 +5,19 @@ description: "Monitor public resource targets and automatically remove unhealthy

 Health checks for public resources monitor each target and keep bad targets out of traffic automatically. When a target fails its check, Pangolin marks it unhealthy and removes it from load balancing. When it recovers and passes again, Pangolin adds it back.

+## Benefits
+
+- Traffic is only sent to targets that are responding, so users don't hit a broken backend.
+- Failover and recovery are automatic, with no manual changes to the resource.
+- Thresholds keep a brief blip from pulling a target out of rotation.
+- Health status feeds [alert rules](/manage/alerting/alert-rules) and the [maintenance page](/manage/resources/public/maintenance), so you can notify admins and users when something fails.
+
+## Use cases
+
+- Keep a web app online when one of several servers goes down or restarts.
+- Fail over between sites in different locations for disaster recovery.
+- Roll out an update one target at a time while the others keep serving traffic.
+
 ## How it works

 For every target on a public resource, Pangolin runs checks at your configured intervals and evaluates the result against your health criteria.
@@ -7,6 +7,23 @@ HTTP and HTTPS public resources are the most common public resource type. They e

 Users open the resource URL in any web browser. No Pangolin client is required.

+## Benefits
+
+- Publish apps from behind NAT or a firewall without opening inbound ports or needing a public IP on the backend.
+- Every resource gets a valid TLS certificate that Pangolin issues and renews.
+- Unauthenticated visitors are stopped at Pangolin before any traffic reaches your app.
+- SSO, identity providers, and context rules like geo-blocking protect apps that have no login of their own.
+- Multiple targets across sites give load balancing, health checks, and automatic failover.
+- Users only need a browser, so contractors, customers, and personal devices can get access without installing anything.
+
+## Use Cases
+
+- Put self-hosted apps such as Grafana, Home Assistant, or an internal wiki behind SSO.
+- Publish a public website or API running on a home server or private network.
+- Share a staging site with a client using a PIN, passcode, or expiring link.
+- Restrict an admin panel to certain countries, IP ranges, or URL paths with access rules.
+- Load balance a web app across servers in different locations.
+
 ## How It Works

 1. You assign a FQDN on a domain managed in Pangolin.
@@ -12,6 +12,18 @@ Pangolin can display a customizable maintenance page to users when a resource is
    <img src="/images/maintenance_page.png" alt="Maintenance Page Preview"/>
 </Frame>

+## Benefits
+
+- Users see a clear message you write instead of a gateway error when a resource is down.
+- An estimated completion time sets expectations and cuts down on support requests.
+- Automatic mode covers unplanned outages without anyone having to switch it on.
+
+## Use Cases
+
+- Announce a planned maintenance window for an app or API.
+- Tell users a service is temporarily unavailable when every target fails its health check.
+- Hold a page in place while you migrate a resource to new servers.
+
 ## Configuration

 Title: The main title text displayed on the maintenance page.
@@ -9,6 +9,28 @@ Because TCP and UDP resources are not protocol-aware, they do **not** enforce Pa

 For workloads that do not need a public proxy, prefer a [private host or CIDR resource](/manage/resources/understanding-resources#private-resource-types) so traffic stays on the zero-trust tunnel with full access control.

+## Benefits
+
+- Expose any TCP or UDP service, whatever the protocol, without opening ports on the backend network.
+- The backend stays behind NAT or a firewall. Only the Pangolin server needs a public port.
+- Players or users connect with their normal client software, with no Pangolin client to install.
+- Multiple targets across sites give round-robin routing and failover.
+- Proxy Protocol can pass the original client IP through to backends that support it.
+
+## Use Cases
+
+- Host a game server, such as Minecraft, from a home network.
+- Publish a VoIP, MQTT, or other non-HTTP service that clients reach by host and port.
+- Give public access to a service that has its own authentication and needs no extra layer from Pangolin.
+
+## How TCP and UDP Resources Work
+
+1. You map a port on the Pangolin server to the resource.
+2. A client connects to `<pangolin-server>:<port>`.
+3. Pangolin forwards the traffic as-is through the tunnel to a site, which delivers it to the target.
+
+Pangolin does not inspect or authenticate the traffic, so any security has to come from the service itself.
+
 ## Target Configuration

 TCP and UDP resources use **[targets](/manage/resources/public/targets)** like HTTP/HTTPS resources:
@@ -9,6 +9,20 @@ RDP public resources render a full Remote Desktop Protocol client in the browser
  <img src="/images/rdp-public.gif" alt="Remote desktop session rendered in the Pangolin web dashboard" />
 </Frame>

+## Benefits
+
+- Users get a Windows desktop from any browser, with no remote desktop software or Pangolin client to install.
+- Port 3389 is never exposed to the internet, which removes a common target for brute-force attacks.
+- SSO, identity providers, and access rules sit in front of Windows authentication.
+- File transfer and clipboard copy and paste work in the browser session.
+
+## Use Cases
+
+- Let staff reach their office workstation from home or a personal device.
+- Give vendors or support staff time-limited access to a Windows server.
+- Reach Windows machines on a factory floor, lab, or branch office behind NAT.
+- Use Windows-only line-of-business apps from Mac, Linux, or Chromebook devices.
+
 ## Video Walkthrough

 <iframe
@@ -13,6 +13,23 @@ Resource policies let you define authentication and access rule settings once an
 Resource policies currently apply to **public resources** only. Support for private resources is coming soon.
 </Note>

+## Benefits
+
+- Define authentication and access rules once instead of repeating them on every resource.
+- A change to a policy applies to every linked resource at once, so resources don't drift apart.
+- Resources can still add their own users, roles, and rules on top of the shared baseline.
+- A consistent baseline makes it easier to see and review how your public resources are protected.
+
+## Use Cases
+
+- Require SSO and block the same set of countries on every app a team publishes.
+- Apply one IP allow list to all internal tools, then grant individual apps to extra roles.
+- Keep the same PIN or email OTP settings across a group of resources shared with a client.
+
+## How Resource Policies Work
+
+A public resource either has its own inline policy or links to a shared policy. When it links to one, it inherits every setting in that policy, and those settings show as read-only on the resource. Users, roles, and access rules you add on the resource combine with the shared policy rather than replacing it. See [Additive Policies](#additive-policies).
+
 ## What a Resource Policy Contains

 A resource policy holds the same settings you configure on a public resource's authentication and access tabs:
@@ -9,6 +9,20 @@ SSH public resources render a full interactive terminal in the browser. Users vi
  <img src="/images/ssh-public.gif" alt="Interactive SSH terminal rendered in the Pangolin web dashboard" />
 </Frame>

+## Benefits
+
+- Users get a terminal from any browser, with no SSH client, keys, or Pangolin client on their device.
+- The host's SSH port is never exposed to the internet. Pangolin authentication happens before a session can start.
+- SSO, identity providers, and access rules like geo-blocking apply to shell access.
+- With automated provisioning, users are created on the host from their Pangolin identity, so there are no shared accounts or keys to manage.
+
+## Use Cases
+
+- Get emergency access to a server from a borrowed or locked-down computer.
+- Give contractors shell access to a single server without setting up a VPN or SSH keys for them.
+- Manage home lab or edge devices from a phone or tablet.
+- Let support staff reach customer appliances behind NAT through a site.
+
 ## Video Walkthrough

 <iframe
@@ -5,6 +5,19 @@ description: "View and control a remote display through a VNC client rendered in

 VNC public resources render a full VNC client in the browser. Users visit a FQDN, complete Pangolin authentication, and get an interactive remote display session without installing a VNC viewer.

+## Benefits
+
+- Users get a remote display from any browser, with no VNC viewer or Pangolin client to install.
+- The VNC server is never exposed to the internet. Pangolin authentication happens before a session can start.
+- SSO, identity providers, and access rules protect VNC servers that often have weak or no passwords of their own.
+- Works with Linux desktops, macOS screen sharing, and embedded devices that expose a VNC server.
+
+## Use Cases
+
+- Remotely support a Linux or macOS desktop.
+- Reach the display of a kiosk, digital sign, or industrial HMI panel behind NAT.
+- Get console access to a virtual machine whose hypervisor exposes VNC.
+
 ## How It Works

 1. You assign a FQDN on a domain managed in Pangolin.
@@ -11,6 +11,26 @@ With a wildcard public resource, one resource owns an entire subdomain level: ev

 Access rules and authentication you set on that resource apply to all hostnames matched by the wildcard. If you enable a PIN code, every hostname under the wildcard requires that PIN. You can also attach a [resource policy](/manage/resources/public/resource-policies) so the same shared settings apply to the wildcard and any other linked public resources.

+## Benefits
+
+- New hostnames work as soon as your downstream proxy serves them, with no new resource in Pangolin.
+- One set of authentication and access rules protects every hostname at that level.
+- Downstream routing keeps working, since the original `Host` header is passed through.
+- A single wildcard certificate covers every hostname, so there is no certificate to issue per app.
+
+## Use Cases
+
+- Put a Kubernetes ingress controller or an existing reverse proxy such as Traefik, Caddy, or nginx behind Pangolin.
+- Give each pull request or branch its own preview URL, such as `pr-123.preview.example.com`.
+- Host per-customer or per-tenant subdomains for a multi-tenant app.
+
+## How Wildcard Resources Work
+
+1. You set the resource's subdomain to `*`, optionally under a parent such as `*.apps`.
+2. DNS sends every hostname at that level to Pangolin, which serves a wildcard certificate for it.
+3. Pangolin applies the resource's authentication and access rules to the request.
+4. The request goes through the tunnel to the target with its original `Host` header, and your downstream proxy routes it to the right app.
+
 ## Creating a Wildcard Resource

 In the resource’s domain settings, set the subdomain field to `*` to match any label at that level. You can combine this with a parent subdomain, such as `*.apps`, so only hostnames under `apps` are covered, as long as TLS and DNS cover that same scope.
@@ -5,6 +5,30 @@ description: "SSH configuration, setup, and examples for public and private reso

 This page explains the configuration options shared by both resource types, gives a concrete example for every valid combination, and walks through host setup for **Standard SSH Server** automated provisioning.

+## Benefits
+
+- SSH servers are never exposed to the public internet. Users reach them through a [public resource](/manage/resources/public/ssh) in the browser or a [private resource](/manage/resources/private/ssh) over the Pangolin client.
+- Automated provisioning signs short-lived certificates from your organization's CA, so there are no long-lived keys on servers.
+- User accounts are created just in time from Pangolin identities, with sudo access and groups set per role.
+- Pangolin SSH mode works without an SSH server or OpenSSH configuration on the host.
+- Access follows your users and roles. Removing someone in Pangolin removes their path to every server.
+
+## Use Cases
+
+- Replace shared accounts and copied `authorized_keys` files with per-user access tied to SSO.
+- Give a team access to a fleet of servers behind a single bastion running a Pangolin Site.
+- Limit some roles to no sudo or a fixed set of sudo commands on production hosts.
+- Sign keys with `pangolin ssh sign` for tools that open their own SSH connections.
+
+## How SSH Access Works
+
+1. A user starts a session in the browser on a public resource, or with `pangolin ssh <alias>` on a private resource.
+2. Pangolin checks that the user has access to the resource.
+3. With manual authentication, the user signs in with credentials that already exist on the host. With automated provisioning, Pangolin makes sure an account exists for the user and authenticates them, using a short-lived signed certificate in Standard SSH Server mode.
+4. The session runs on the site host in Pangolin SSH mode, or is routed to an SSH server on the network in Standard SSH Server mode.
+
+See [How Certificates Work](#how-certificates-work) and [How Users and Access Are Managed](#how-users-and-access-are-managed) for details.
+
 ## Video Walkthrough

 <iframe