cianfhoghlaim/cianchosaint / .agents/skills/pangolin
pangolin
Verifiedname: 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:
- 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.
- 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. - Sites integrated into the Pangolin CLI —
pangolin up site --id <id> --secret <secret> --endpoint <endpoint>is now the canonical command. - Master list of organizations in the server admin panel.
- Multiple server admin users supported (promote/demote via the users table).
- Resource Launcher side panel — Sites widget + ready-to-copy
pangolin sshcommands 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) viabonneagar/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 patternbonneagar/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
- Separate Networks: Use dedicated Docker networks for Pangolin
- TLS Everywhere: Always use HTTPS with Traefik
- Peer Naming: Use descriptive names (user-device-purpose)
- Regular Key Rotation: Rotate WireGuard keys periodically
- Access Logging: Enable Traefik access logs
- Health Checks: Configure health checks for services
- 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
- 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).
# 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:
| 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 (includespangolin.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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |