DOCSEARCHbyAlgolia
Submit Docs

Pangolin Documentation

website·Indexed 34 days ago

https://docs.pangolin.net/

Documentation for Pangolin, a connectivity platform providing secure access to remote networks via a Pangolin Server, sites, and clients. It features an AI Gateway for LLM API proxying, support for SSH, RDP, VNC, and HTTP/HTTPS resources, and deployment options for Cloud, self-hosted, and Kubernetes using Helm.

Tokens
137.6K
Snippets
599
Records
962
Agent score
67%

What's inside Pangolin

  1. Overview of Pangolin Cluster Architecture

    Pangolin clustering (available only in the Enterprise Edition) allows multiple server instances to operate as a unified system for high availability, regional distribution, and horizontal scaling. All instances share state via a centralized PostgreSQL database and a Valkey (Redis) server. Each node runs a Pangolin instance, a Gerbil tunnel manager, and a Traefik instance.

  2. Overview of Pangolin AI Gateway

    The AI Gateway is a Pangolin resource that proxies requests to upstream AI providers (such as OpenAI, Anthropic, Google Gemini, Bedrock, Vertex AI, or custom endpoints). It provides centralized authentication, access control, and logging. Clients point to the gateway's URL instead of the provider's URL. The gateway supports the API formats of its attached providers (e.g., an Anthropic provider enables the Anthropic Messages API).

  3. Overview of Pangolin Public and Private Resources

    Resources are network addresses made available to users. They exist on remote site networks and are accessed via the Resource Launcher.

    • Public Resources: Protocol-aware reverse proxies on the public internet. They support browser-based access (no client required) and use protocol-aware authentication/access rules.
    • Private Resources: Zero-trust VPN access requiring the Pangolin client. Every private resource requires authentication and cannot be rendered in a browser without the client.

  5. Use Labels to organize sites, clients, and resources

    Labels are reusable string-based metadata tags available in Pangolin Cloud and Enterprise Edition. They allow you to group related entities across different types and improve searchability.

    Supported Entities:

    • Sites
    • Machine clients
    • Resources

    Key Capabilities:

    • Cross-Entity Grouping: The same label can be applied to a site, a client, and a resource. This allows you to group all components of a specific location or project (e.g., tagging everything related to warehouse-1).
    • Search and Filtering: Entities tagged with a label become searchable by that string and can be filtered within the respective entity table views.
    • Flexible Metadata: Labels are plain strings, allowing for custom naming conventions such as environments (prod, dev), operating systems (linux, windows), or locations (us-east).

  6. Pangolin Kubernetes Component Overview

    Pangolin deployments on Kubernetes consist of several key components:

    • Pangolin: Main application (Dashboard, API, Auth, Config, Database state).
    • Gerbil: Tunnel stack component for site connectivity.
    • Site (Newt): Site connector for connecting private resources to Pangolin.
    • Traefik: Reverse proxy and router for ingress traffic.
    • PostgreSQL / SQLite: Database options based on chart configuration.
    • Pangolin Kube Controller: Integrates Pangolin with Kubernetes and Traefik resources.

  7. Understand the role of Pangolin Nodes

    A node acts as the networking edge of a Pangolin deployment. It terminates inbound public internet traffic, manages WireGuard tunnels, and relays client traffic when direct peer-to-peer paths are unavailable. In a standard self-hosted deployment, the server runs as a single node. Enterprise deployments can use clustering for high availability, and Pangolin Cloud supports 'remote nodes' (user-operated infrastructure managed by the cloud control plane).

    Nodes consist of three primary cooperating processes:

    • Traefik (Ingress/Reverse Proxy): Terminates TLS, routes HTTP(S) and protocol-aware public resources, and forwards authenticated requests.
    • Gerbil (Tunnel Manager): Maintains WireGuard peers for site connectors and clients, performs SNI-based routing, and relays UDP traffic.
    • Badger (Auth Middleware): A Traefik plugin that enforces Pangolin authentication on public resources via forward auth.

  8. Understand the purpose of the Community Blueprints repository

    The Community Blueprints repository provides reusable patterns for self-hosting applications. It specifically addresses the complexities of networking, exposure, and access control by offering known-good templates for popular services. Using these blueprints allows developers to avoid repetitive reverse proxy configurations, implement secure SSO-oriented access patterns, ensure deployment consistency across environments, and contribute to community-driven improvements of hosting patterns.

  9. Understand Public Resource types and access models

    Public resources create a public proxy on the Pangolin server. Traffic enters through Pangolin and is forwarded to a backend on a remote site.

    • Browser-based Resources (HTTP/HTTPS, SSH, RDP, VNC): These are assigned a fully qualified domain name (FQDN) and accessed via a web browser. They are protected by Pangolin authentication and access rules.
    • AI Gateway: Assigned a public FQDN. Coding agents call it as an API; users visit the URL in a browser to retrieve virtual API keys.
    • Protocol-Agnostic Pipes (TCP, UDP): These do not receive an FQDN. Instead, they bind to a port on the Pangolin server host. Because they are not protocol-aware, they do not enforce Pangolin authentication or access rules.

  11. Monitor and analyze Authentication Logs

    Authentication logs record every authenticated access attempt to Pangolin resources by users or API keys. They are used to monitor login patterns, track resource access, identify failed authentication attempts for security analysis, and analyze geographic distribution and device information.

    Availability: Only available in Pangolin Cloud or self-hosted Enterprise Edition.

    Setup: Authentication logs must be enabled in the organization settings.

  12. Compare Pangolin Community Edition and Enterprise Edition

    Pangolin offers two self-hosted editions. Both provide the same core functionality, but the Enterprise Edition unlocks additional features via a license key and a specific Docker image.

    • Community Edition: Standard version.
    • Enterprise Edition: Unlocks advanced capabilities. It is free for individuals and organizations with less than $100,000 USD gross annual revenue, but requires a valid license key. Organizations with $100,000+ USD gross annual revenue require a paid commercial license.