---
title: "How Pangolin Works"
description: "Learn about Pangolin's architecture and how its components work together to provide secure application access"
---

## System Overview

Pangolin operates through a central server (called the point of presence) that manages connections to your edge networks. Each edge network runs a lightweight client that establishes secure tunnels back to the central server.

<Frame caption="System architecture showing Pangolin components and their interactions">
<img src="/images/system-diagram.svg" alt="Pangolin system architecture diagram"/>
</Frame>

## Core Components

### Pangolin (Control Plane)

Pangolin is the main control center that orchestrates the entire system:

- **Web Interface**: Management dashboard for configuring sites, users, and access policies
- **REST API**: External API for automation and integration
- **WebSocket Server**: Manages real-time connections to edge network clients
- **Authentication System**: Handles user authentication and authorization
- **Database**: Stores configuration, user data, and system state

<Info>
Pangolin acts as the brain of the system, coordinating all other components and managing user access.
</Info>

### Gerbil (Tunnel Manager)

Gerbil manages the secure WireGuard tunnels between your edge networks and the central server:

- **Peer Management**: Creates and maintains WireGuard connections
- **Tunnel Orchestration**: Handles tunnel creation, updates, and cleanup
- **Security**: Ensures all traffic is encrypted using WireGuard's cryptographic protocols

<Check>
WireGuard provides fast, secure, and reliable tunneling with minimal overhead.
</Check>

### Newt (Edge Client)

Newt is a lightweight client that runs on your edge networks (servers, VMs, or containers):

- **Automatic Discovery**: Finds the optimal point of presence for best performance
- **Dual Connection**: Connects to Pangolin via WebSocket and Gerbil via WireGuard
- **Resource Proxy**: Creates TCP/UDP proxies to expose your applications securely

<Tip>
Newt is designed to be resource-efficient and can run on minimal hardware or in containers.
</Tip>

### Reverse Proxy (Router)

The reverse proxy handles incoming requests and routes them to your applications:

- **Request Routing**: Directs traffic to the correct backend services
- **SSL Termination**: Manages HTTPS certificates and encryption
- **Middleware Support**: Integrates with security and monitoring plugins

### Badger (Authentication Middleware)

Badger is Pangolin's middleware that enforces access control:

- **Request Interception**: Catches all incoming requests before they reach your applications
- **Authentication Check**: Verifies user identity and permissions
- **Secure Redirects**: Sends unauthenticated users to Pangolin's login system

<Warning>
Badger ensures that only authenticated and authorized users can access your applications, even if they bypass other security measures.
</Warning>

## How It All Works Together

<Steps>
<Step title="User requests access">
  A user tries to access your application through the public domain.
</Step>

<Step title="Badger intercepts the request">
  Badger middleware catches the request and checks if the user is authenticated.
</Step>

<Step title="Authentication redirect">
  If not authenticated, the user is redirected to Pangolin's login system.
</Step>

<Step title="Secure tunnel access">
  Once authenticated, requests flow through the encrypted WireGuard tunnel managed by Gerbil.
</Step>

<Step title="Application delivery">
  The reverse proxy routes the request to your application running behind Newt on the edge network.
</Step>
</Steps>

## Deployment Models

<CardGroup cols={2}>
<Card title="Pangolin Cloud" icon="cloud" href="https://pangolin.fossorial.io/auth/signup">
  Use Cloud for a highly available and access-controllerd ingress service with points of presence all over the world.
</Card>

<Card title="Self-Hosted" icon="server" href="/self-host/quick-install">
  All components run on your infrastructure, giving you complete control over security and data.
</Card>
</CardGroup>