Skip to content

cianfhoghlaim/cianchosaint / .agents/skills/pangolin

pangolin

Verified

<!--
CIANCHOSAINT wholesale-copy of cianfhoghlaim/cianfhoghlaim @ main branch.

Original: cianfhoghlaim/cianfhoghlaim (per the openspec/changes/cianchosaint-repo-bootstrap-v2/specs/cianchosaint-bootstrap-v2/spec.md).
Migrated to cianchosaint: 2026-08-23
Licence: BUSL-1.1 (per LICENSE.md)

UPDATED 2026-09-26 (per the openspec/changes/2026-09-26-pangolin-newt-v1.23-upgrade-v1/
specs/pangolin-stack/spec.md, Stage 2a of the package-version-drift saga):
- Bumped version to 1.23.0 (Sep 15, 2026 release)
- Added "What's new in Pangolin 1.23" section
- Updated Newt → Pangolin Site rename documentation
- Updated Gerbil version to 1.5.1
-->
---
name: pangolin
description: Expert assistance for Fossorial Pangolin network infrastructure. Use when users need VPN configuration, reverse proxy setup, Traefik integration, WireGuard tunnels, secure private network access. Covers v1.23.0 (Sep 2026) with the Newt → Pangolin Site rename + self-service HA/clustering.
---

# Pangolin - Network Infrastructure Platform

**Version:** 1.23.0 | **Last Updated:** 2026-09-26
**Upstream docs:** https://docs.pangolin.net (Mintlify-hosted)
**Repo:** https://github.com/fosrl/pangolin  (note: `fosrl`, not `fossoriale`)
**Pangolin Site (was Newt):** https://github.com/fosrl/pangolin-cli (v1.23+ — the CLI that supersedes the standalone Newt binary)
**Newt connector (legacy):** https://github.com/fosrl/newt (existing deployments keep working per v1.23 docs)
**Gerbil:** v1.5.1 (Aug 31, 2026 — latest)
**Private AI Gateway:** requires clients post-2026-08-19 (per v1.23 release notes)

## Overview

Pangolin is a network infrastructure management platform:

- **VPN**: WireGuard-based secure tunneling
- **Reverse Proxy**: Traefik integration for routing
- **Access Control**: Fine-grained network permissions
- **Service Discovery**: Automatic service registration
- **Docker Integration**: Container-aware networking

 **Repository**: https://github.com/fosrl/pangolin  (renamed from `fossoriale`)

## What's new in Pangolin 1.23 (Sep 15, 2026)

Per the [v1.23 release blog](https://pangolin.net/news/1-23-release):

1. **Self-service high availability and clustering** on Scale + Enterprise tiers. DNS resolution + certificate management that used to live outside the stack now run inside Pangolin itself.
2. **Newt renamed to Pangolin Site** — the dashboard now treats the CLI method (`fosrl/pangolin-cli`) as the preferred, default way to install a new site.
3. **Sites integrated into the Pangolin CLI** — `pangolin up site --id <id> --secret <secret> --endpoint <endpoint>` is now the canonical command.
4. **Master list of organizations** in the server admin panel.
5. **Multiple server admin users** supported (promote/demote via the users table).
6. **Resource Launcher side panel** — Sites widget + ready-to-copy `pangolin ssh` commands for SSH private resources.

**The "Newt → Pangolin Site" rename migration** (the load-bearing change):

- The standalone Newt binary (`fosrl/newt:1.16.x`) **continues to work** per v1.23 docs: *"Existing Newt deployments keep working. Leave them as they are, or switch to the CLI when you want to. Newt will continue to be provided in all of its current forms for the foreseeable future."*
- New deployments SHOULD use `fosrl/pangolin-cli` (the v1.23+ canonical pattern) via `bonneagar/stacks/pangolin-site/`.
- The dashboard now shows "Pangolin Site" as the canonical name, but recognises the legacy Newt binary.

**Per the 2026-09-26-pangolin-newt-v1.23-upgrade-v1 openspec change** (Stage 2a of the package-version-drift saga):
- `bonneagar/stacks/pangolin/compose.yaml` — `pangolin: image: fosrl/pangolin:ee-1.23.0` (pinned)
- `bonneagar/stacks/pangolin/compose.yaml` — `gerbil: image: fosrl/gerbil:1.5.1` (pinned)
- `bonneagar/stacks/pangolin-site/` (NEW) — the v1.23+ canonical new-site pattern
- `bonneagar/stacks/pangolin/newt.yaml` (kept for backward compat; header comment added)

## When to Use This Skill

Activate when users need:

- "Set up VPN access to services"
- "Configure reverse proxy routing"
- "Create secure tunnels to private networks"
- "Set up Traefik with WireGuard"
- "Configure Pangolin network access"

## Core Concepts

### 1. Architecture

```
┌────────────────────────────────────────────────┐
│                  Internet                       │
└───────────────────┬────────────────────────────┘
                    │
         ┌──────────▼──────────┐
         │      Traefik        │
         │   (Reverse Proxy)   │
         │     :80, :443       │
         └──────────┬──────────┘
                    │
         ┌──────────▼──────────┐
         │      Pangolin       │
         │   (Control Plane)   │
         │       :3001         │
         └──────────┬──────────┘
                    │
         ┌──────────▼──────────┐
         │      Gerbil         │
         │   (WireGuard VPN)   │
         │      :51820/udp     │
         └──────────┬──────────┘
                    │
    ┌───────────────┼───────────────┐
    ▼               ▼               ▼
┌───────┐      ┌───────┐       ┌───────┐
│Service│      │Service│       │Service│
│   A   │      │   B   │       │   C   │
└───────┘      └───────┘       └───────┘
```

### 2. Docker Compose Setup

```yaml
# compose.yaml
services:
  pangolin:
    image: ghcr.io/fosrl/pangolin:latest
    ports:
      - "3001:3001"
    volumes:
      - ./config:/app/config
      - pangolin-data:/app/data
    environment:
      - PANGOLIN_SECRET=${PANGOLIN_SECRET}
    networks:
      - pangolin

  gerbil:
    image: ghcr.io/fosrl/newt:latest
    cap_add:
      - NET_ADMIN
    ports:
      - "51820:51820/udp"
    volumes:
      - ./wireguard:/etc/wireguard
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
    networks:
      - pangolin

  traefik:
    image: traefik:v3.0
    command:
      - "--api.insecure=true"
      - "--providers.docker=true"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
    ports:
      - "80:80"
      - "443:443"
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - pangolin

networks:
  pangolin:
    driver: bridge

volumes:
  pangolin-data:
```

### 3. Traefik Configuration

```yaml
# config/traefik.yaml
entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
  websecure:
    address: ":443"

providers:
  docker:
    exposedByDefault: false
    network: pangolin
  file:
    directory: /etc/traefik/dynamic
    watch: true

certificatesResolvers:
  letsencrypt:
    acme:
      email: admin@example.com
      storage: /letsencrypt/acme.json
      httpChallenge:
        entryPoint: web
```

### 4. Service Routing

```yaml
# Dynamic Traefik configuration
http:
  routers:
    my-service:
      rule: "Host(`service.example.com`)"
      entryPoints:
        - websecure
      service: my-service
      tls:
        certResolver: letsencrypt

  services:
    my-service:
      loadBalancer:
        servers:
          - url: "http://internal-service:8080"
```

### 5. WireGuard Client Configuration

```ini
# client.conf (generated by Pangolin)
[Interface]
PrivateKey = <client_private_key>
Address = 10.0.0.2/32
DNS = 10.0.0.1

[Peer]
PublicKey = <server_public_key>
Endpoint = vpn.example.com:51820
AllowedIPs = 10.0.0.0/24, 192.168.1.0/24
PersistentKeepalive = 25
```

### 6. Pangolin API Usage

```typescript
// Connect to Pangolin API
const pangolin = {
  baseUrl: "http://localhost:3001/api/v1",

  async createPeer(config: PeerConfig) {
    const response = await fetch(`${this.baseUrl}/peers`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(config)
    })
    return response.json()
  },

  async listPeers() {
    const response = await fetch(`${this.baseUrl}/peers`)
    return response.json()
  },

  async getTraefikConfig() {
    const response = await fetch(`${this.baseUrl}/traefik-config`)
    return response.json()
  }
}

// Create new VPN peer
const peer = await pangolin.createPeer({
  name: "developer-laptop",
  allowedIPs: ["10.0.0.100/32"],
  dns: ["10.0.0.1"]
})

console.log("WireGuard config:", peer.config)
```

### 7. Service Labels for Traefik

```yaml
# docker-compose service with Traefik labels
services:
  api:
    image: my-api:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.api.rule=Host(`api.example.com`)"
      - "traefik.http.routers.api.entrypoints=websecure"
      - "traefik.http.routers.api.tls.certresolver=letsencrypt"
      - "traefik.http.services.api.loadbalancer.server.port=3000"
    networks:
      - pangolin
```

### 8. Access Control Configuration

```yaml
# config/access.yaml
rules:
  - name: "developers"
    peers:
      - "developer-*"
    allowed_services:
      - "api.internal"
      - "dashboard.internal"
      - "*.dev.internal"

  - name: "production"
    peers:
      - "prod-server-*"
    allowed_services:
      - "*"

  - name: "monitoring"
    peers:
      - "monitoring-agent"
    allowed_services:
      - "prometheus.internal"
      - "grafana.internal"
```

### 9. Integration with Komodo

```toml
# Komodo stack for Pangolin-protected service
[[stack]]
name = "internal-api"
description = "API accessible via Pangolin VPN"

[stack.config]
server = "internal-server"
repo = "company/internal-api"
branch = "main"

[stack.config.environment]
PANGOLIN_NETWORK = "true"
ALLOWED_HOSTS = "api.internal"

[[stack.config.labels]]
traefik.enable = "true"
traefik.http.routers.api.rule = "Host(`api.internal`)"
```

## Deployment Commands

```bash
# Start Pangolin infrastructure
cd infrastructure/compose/pangolin
docker compose up -d

# Check status
docker ps

# View Traefik config
curl http://localhost:3001/api/v1/traefik-config

# Access API docs
open http://localhost:3001/v1/docs

# Connect via VPN
wg-quick up ./client.conf

# Check VPN status
wg show

# Disconnect
wg-quick down ./client.conf
```

## Network Patterns

### Pattern 1: Public + Private Services
```
Internet → Traefik → Public services (HTTPS)
                   ↓
VPN Peers → Gerbil → Private services (internal)
```

### Pattern 2: Zero-Trust Access
```
All services behind VPN
Traefik → authenticates → routes to services
Each service requires VPN connection
```

### Pattern 3: Hybrid Cloud
```
Cloud VPC ←→ Pangolin ←→ On-premise
           WireGuard tunnel
```

## Best Practices

1. **Separate Networks**: Use dedicated Docker networks for Pangolin
2. **TLS Everywhere**: Always use HTTPS with Traefik
3. **Peer Naming**: Use descriptive names (user-device-purpose)
4. **Regular Key Rotation**: Rotate WireGuard keys periodically
5. **Access Logging**: Enable Traefik access logs
6. **Health Checks**: Configure health checks for services
7. **DNS Configuration**: Use internal DNS for service discovery

## Troubleshooting

### VPN Not Connecting
```bash
# Verify UDP port is open
nc -vzu vpn.example.com 51820

# Check WireGuard config
wg show

# Check Gerbil container
docker logs pangolin-gerbil-1

# Verify kernel modules
lsmod | grep wireguard
```

### Service Not Accessible
```bash
# Check Traefik routing
curl http://localhost:8080/api/rawdata/routers

# Verify service is on correct network
docker network inspect pangolin

# Check service labels
docker inspect <container> | grep -A 20 Labels
```

### DNS Resolution Issues
```bash
# Test DNS resolution
dig @10.0.0.1 service.internal

# Check DNS configuration
cat /etc/resolv.conf

# Verify Gerbil DNS
docker exec pangolin-gerbil-1 cat /etc/resolv.conf
```

## Environment Setup

```bash
# Required environment variables
export PANGOLIN_SECRET=$(openssl rand -hex 32)
export TRAEFIK_ACME_EMAIL=admin@example.com

# Generate WireGuard keys
wg genkey | tee server_private.key | wg pubkey > server_public.key

# Create configuration directory
mkdir -p config wireguard
```

## Resources

- **Traefik Docs**: https://doc.traefik.io/traefik/
- **WireGuard Docs**: https://www.wireguard.com/
- **Pangolin API**: http://localhost:3001/v1/docs
- **Docker Networking**: https://docs.docker.com/network/

## Cianfhoghlaim integration (canonical)

The Cianfhoghlaim platform uses Pangolin in a **convergence
architecture**:

```
┌──────────────────────────────────────────────────────────┐
│  Control plane (arm1-oci)                                │
│  → routing, identity (Pocket ID), orchestration (Komodo) │
└──────────────────────────────────────────────────────────┘
              ↓ WireGuard tunnel
┌──────────────────────────────────────────────────────────┐
│  Workload host (bunchloch MacBook M4)                    │
│  → memory-intensive workloads (LanceDB, Cognee,        │
│    LLM inference, local analytics)                        │
└──────────────────────────────────────────────────────────┘
```

All inter-tier communication is via WireGuard tunnels; no
inbound firewall ports.

### Pocket ID OIDC (admin SSO)

Pangolin uses **Pocket ID** for admin SSO. Admin users
authenticate via WebAuthn passkeys (no passwords).

```yaml
# Pangolin resource config (in komodo)
pangolin.oidc:
  provider: pocketid
  client_id: cianfhoghlaim-admin
  client_secret: ${INFISICAL:POCKETID_CLIENT_SECRET}
  issuer_url: https://pocketid.cianfhoghlaim.ie
```

### CrowdSec (anti-bruteforce)

The Cianfhoghlaim Pangolin instance fronts CrowdSec for anti-bruteforce.
CrowdSec runs as a service **inside the Pangolin stack** at
`infrastructure/stacks/pangolin/compose.yaml`, not as a
standalone stack:

```yaml
# infrastructure/stacks/pangolin/compose.yaml  (the crowdsec service)
services:
  crowdsec:
    image: crowdsecurity/crowdsec:latest
    volumes:
      - ./config:/etc/crowdsec
    environment:
      COLLECTIONS: crowdsecurity/linux crowdsecurity/cf-cf-connect crowdsecurity/http-cve crowdsecurity/wordpress crowdsecurity/dovecot
```

### 6-label Docker pattern

Every Compose stack that exposes a web route uses the
canonical 6-label Pangolin resource:

```yaml
# infrastructure/stacks/<name>/pangolin.yaml
pangolin.private-resources.<name>:
  - name: <name>
    mode: http
    full-domain: <name>.cianfhoghlaim.ie
    destination-port: 8080
    protocol: http
    roles:
      - "<role-name>"
```

The 6 labels (in order): `name`, `mode`, `full-domain`,
`destination-port`, `protocol`, `roles[0]`. No variation.

### Multi-site HA

For the canonical Cianfhoghlaim production deploy:

```yaml
pangolin.sites:
  - name: arm1-oci-prod
    url: https://pangolin.cianfhoghlaim.ie
    type: local
  - name: bunchloch-mac
    url: https://bunchloch.cianfhoghlaim.local
    type: local
```

### Tunneled Periphery access

For accessing a Periphery node behind NAT (e.g. a home
workstation running a dev stack):

```bash
# On the Periphery node
pangolin-cli tunnel-up \
  --site arm1-oci-prod \
  --port 8080 \
  --name bunchloch-dev
```

The Periphery node is then reachable at
`https://bunchloch-dev.cianfhoghlaim.ie` from the control
plane.

### 3-tier host convergence (the canonical Cianfhoghlaim topology)

Cianfhoghlaim runs across **3 hosts**, not 1 or 2. Pangolin
WireGuard tunnels wire them together:

| Tier | Host | Role | Pangolin role |
|:--|:--|:--|:--|
| **Control plane** | `arm1-oci` (Oracle Cloud ARM free tier) | Komodo (GitOps) + Pocket ID (OIDC) + CrowdSec (WAF) | Pangolin Core :3001 + Gerbil :51820/udp |
| **Storage** | `cax41-hetzner` (Hetzner cax41) | Garage S3 + Lakekeeper Iceberg REST + Postgres | Pangolin routing for `*.cianfhoghlaim.ie` |
| **Workload** | `bunchloch` (MacBook M4 Max) | Dagster + LiteLLM + the 70+ model servers | Tunneled via Newt → Gerbil |

The 3 hosts are wired by **Newt tunnel agents** (one per
host) and **Pocket ID OIDC SSO** (the single auth provider
for the whole cluster). See
`.agents/skills/bunchloch/SKILL.md` for the full
service map and `.agents/skills/convergence/SKILL.md`
for the 6 docker-compose categories that run on these hosts.

### Related skills

- `.agents/skills/stack-ops/SKILL.md` — the 6-file
  GOLD_STANDARD stack pattern (includes `pangolin.yaml`)
- `.agents/skills/komodo/SKILL.md` — Komodo deploys the
  Pangolin resources
- `.agents/skills/secrets-management/SKILL.md` — the
  3-way secret contract (Pocket ID uses Infisical)
- `.agents/skills/better-auth/SKILL.md` — multi-layer
  auth architecture (BetterAuth → PocketID → TinyAuth →
  Infisical)
- `.agents/skills/monorepo/SKILL.md` — mise + dagger
  deploys the Pangolin control plane
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall