Skip to content

cianfhoghlaim/cianchosaint / .agents/skills/pangolin

pangolin

Verified


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:

  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

# 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

# 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

# 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

# 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

// 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

# 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:

# 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:

# 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:

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

# 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:

TierHostRolePangolin role
Control planearm1-oci (Oracle Cloud ARM free tier)Komodo (GitOps) + Pocket ID (OIDC) + CrowdSec (WAF)Pangolin Core :3001 + Gerbil :51820/udp
Storagecax41-hetzner (Hetzner cax41)Garage S3 + Lakekeeper Iceberg REST + PostgresPangolin routing for *.cianfhoghlaim.ie
Workloadbunchloch (MacBook M4 Max)Dagster + LiteLLM + the 70+ model serversTunneled 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