Early access. Edge mode is usable end-to-end as of the current release: Drydock 1.5 ships the /api/portwing/ws controller endpoint (Ed25519-only) and Portwing signs its hello with an Ed25519 key. Both Drydock 1.5 and the current Portwing release are pre-release; full exec robustness under load is still being hardened.

For hosts behind NAT or a firewall, examples/docker-compose.edge.yml has Portwing dial out to your Drydock controller's edge endpoint (DRYDOCK_URL + /api/portwing/ws); no port is published on the remote host.

services:
  portwing:
    image: ghcr.io/codeswhat/portwing:latest
    restart: unless-stopped
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - /tmp
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - portwing-stacks:/data/stacks
    environment:
      - DRYDOCK_URL=https://drydock.example.com
      - TOKEN_FILE=/run/secrets/portwing_token
      - AGENT_NAME=edge-host-01
      # Key-based hello instead of a shared token:
      #   portwing keygen  →  PRIVATE_KEY_FILE=/run/secrets/portwing_key
    secrets:
      - portwing_token

secrets:
  portwing_token:
    file: ./portwing_token.txt

volumes:
  portwing-stacks:

This is for trying Portwing out locally. Environment-variable tokens are visible in docker inspect and process listings. Do not use in production — use the hardened deployment above instead.

docker run -d \
  --name portwing \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  -e TOKEN=$(openssl rand -hex 24) \
  ghcr.io/codeswhat/portwing:latest

Without TOKEN (or TOKEN_HASH/AUTHORIZED_KEYS) the API is unauthenticated — anyone who can reach the port controls your Docker daemon.

curl -fsSL https://raw.githubusercontent.com/codeswhat/portwing/main/scripts/install.sh | bash

• v0.3.0 shipped on 2026-06-15 — startup banner, Lookout→Portwing rename completed, GoReleaser dockers_v2 migration, and two edge-mode bug fixes (reconnect backoff reset, steady-state read deadline). See CHANGELOG.md.
• v0.2.0 shipped on 2026-06-12 — Ed25519 per-request authentication with signed requests via X-Portwing-Key-ID / X-Portwing-Timestamp / X-Portwing-Nonce / X-Portwing-Signature headers, verified against an authorized_keys file. Replay protection via nonce LRU and timestamp window, SIGHUP hot-reload of the key file, portwing keygen CLI subcommand, and X-Portwing-Reason diagnostic header on 401s. Signed edge-mode hello via PRIVATE_KEY_FILE.
• Key enrollment — optional single-use ENROLLMENT_TOKEN (POST /api/portwing/enroll) for bootstrapping the first Ed25519 key — burned on first use, rate-limited, and audit-logged.
• Argon2id token hashing — TOKEN_HASH / TOKEN_HASH_FILE with OWASP-recommended parameters; SHA-256 success cache keeps per-request cost flat.
• MCP server — read-only Model Context Protocol endpoint at /_portwing/mcp (Streamable HTTP, protocol 2025-11-25) for AI assistants (Claude, Cursor, Windsurf). Tools: list_containers, inspect_container, container_logs, host_metrics, container_stats.
• Prometheus metrics — /metrics and /_portwing/metrics exposing portwing_build_info, container count, and host resource metrics, plus agent request metrics: request totals by method/code (portwing_http_requests_total), a request-duration histogram (portwing_http_request_duration_seconds), in-flight gauge (portwing_http_requests_in_flight), auth-failure counter (portwing_auth_failures_total), and rate-limited counter (portwing_rate_limited_total).
• Structured audit logging — AUDIT_LOG env var records auth events, Compose operations, and exec sessions as JSON lines.
• Generic REST adapter — headless REST + SSE management API for standalone mode without a Drydock platform connection (ADAPTER=generic).
• Hardened CI & supply chain — SHA-pinned actions, five Go fuzz targets (60s CI / 5m nightly), integration suite against a real Docker daemon, weekly vulnerability scans (govulncheck/grype/gosec), monthly mutation testing, OpenSSF Scorecard, CodeQL, and cosign keyless signing + CycloneDX SBOM + SLSA provenance on every release.
• v0.1.0 shipped on 2025-06-01 — initial release: transparent Docker API proxy, Edge mode WebSocket tunnel, Drydock adapter, SSE event stream, token auth, rate limiting, multi-arch image.

See CHANGELOG.md for the full itemized history.

Set TOKEN to a random secret. All requests must supply it via Authorization: Bearer, X-Portwing-Token, or X-Dd-Agent-Secret.

TOKEN=$(openssl rand -hex 32)
docker run -d --name portwing \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e TOKEN="$TOKEN" \
  -p 3000:3000 \
  ghcr.io/codeswhat/portwing:latest

Ed25519 keypairs give per-client identity with per-request signatures and replay protection. No shared secrets.

Generate a keypair:

# Writes the private key (PEM PKCS#8) and the authorized_keys line to stdout.
portwing keygen -comment "my-platform:prod"

Copy the authorized_keys line to the agent host:

# /etc/portwing/authorized_keys  (mode 0600)
ed25519 AAAA... my-platform:prod

Start the agent with Ed25519 auth:

docker run -d --name portwing \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /etc/portwing/authorized_keys:/etc/portwing/authorized_keys:ro \
  -e AUTHORIZED_KEYS=/etc/portwing/authorized_keys \
  -p 3000:3000 \
  ghcr.io/codeswhat/portwing:latest

Key rotation (zero-downtime):

1. Generate a new keypair: portwing keygen -comment "my-platform:prod:2026-07"
2. Append the new public key line to the authorized_keys file on the agent host.
3. Send SIGHUP to reload: kill -HUP $(pidof portwing) or docker kill --signal HUP portwing. Both old and new keys are now active.
4. Update the platform to use the new private key.
5. Remove the old key from the file and send another SIGHUP.

Token auth (TOKEN/TOKEN_HASH) continues to work alongside Ed25519 — both can be set simultaneously during migration. The middleware checks for X-Portwing-Signature first; if absent, it falls back to the token check.

Standard Mode — implemented

Portwing runs an HTTP(S) server; the Drydock controller connects inbound and pulls from it. This is the integration that works today.

• Set when DRYDOCK_URL is not configured
• Drydock authenticates with the X-Dd-Agent-Secret shared secret (optional mTLS)
• Handshake on GET /api/containers · /api/watchers · /api/triggers, then a long-lived SSE stream on GET /api/events
• Transparent Docker API proxy on all paths; agent endpoints under /_portwing/*
• Optional TLS with modern cipher suites (TLS 1.2+)

Edge Mode — early access

Portwing initiates an outbound WebSocket to the controller's edge endpoint (DRYDOCK_URL + /api/portwing/ws) for hosts with no inbound port. Both sides are implemented — Drydock 1.5 ships the controller endpoint and Portwing signs an Ed25519 hello — so edge mode is usable end-to-end as of the current release. Both Drydock 1.5 and the current Portwing release are pre-release; full exec robustness under load is still being hardened. The endpoint is Ed25519-only: set PRIVATE_KEY_FILE and register the public key with Drydock.

• Set when DRYDOCK_URL is configured along with TOKEN, AUTHORIZED_KEYS, or PRIVATE_KEY_FILE
• Targets hosts behind NAT, firewalls, and dynamic IPs
• Auto-reconnect with exponential backoff + jitter; signed hello via PRIVATE_KEY_FILE

DRYDOCK_URL set + (TOKEN or AUTHORIZED_KEYS or PRIVATE_KEY_FILE) set  →  Edge Mode (outbound WebSocket)
Otherwise                                                              →  Standard Mode (inbound HTTP server)

Run Portwing without any external controller by setting ADAPTER=generic. You get a clean REST + SSE API on /api/v1/* backed directly by the local Docker daemon — no Drydock account required.

docker run -d \
  --name portwing \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e ADAPTER=generic \
  -e TOKEN=my-secret \
  -p 3000:3000 \
  ghcr.io/codeswhat/portwing:latest

Endpoints

curl examples

TOKEN=my-secret

# Agent version
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:3000/api/v1/version | jq .

# Container inventory
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:3000/api/v1/containers | jq .

# Last 50 log lines from a container
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3000/api/v1/containers/my-container/logs?tail=50"

# Stream container logs live
curl -sN -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3000/api/v1/containers/my-container/logs?follow=1"

# Stream Docker lifecycle events (SSE)
curl -sN -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/v1/events

Each SSE event is a JSON object:

{
  "ts": "2026-06-11T10:00:00Z",
  "type": "container",
  "action": "start",
  "containerId": "abc123def456",
  "name": "my-container",
  "image": "nginx:latest",
  "labels": { "app": "web" }
}

A comment heartbeat line (: heartbeat) is written every 30 seconds to keep the connection alive through proxies.

Connection

Docker

Agent Identity

Operational

Adapter

Drydock Compatibility

Health Endpoints

/_portwing/health returns HTTP 503 when the Docker daemon is unreachable. Both endpoints are unauthenticated and safe to use for load-balancer probes and Docker HEALTHCHECK instructions.

Agent Endpoints

MCP — AI Assistant Integration

Portwing exposes a read-only Model Context Protocol endpoint at POST /_portwing/mcp. AI assistants (Claude, Cursor, Windsurf, or any MCP client) can query live container state through this endpoint using their standard tool-call flow.

Protocol: MCP 2025-11-25 — Streamable HTTP, stateless single-request mode, Content-Type: application/json.

Available tools:

Credential hygiene: inspect_container returns only the count of environment variables — values are never transmitted, preventing accidental secret leakage.

Add to Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "portwing": {
      "command": "curl",
      "args": ["-s", "-X", "POST",
               "-H", "Content-Type: application/json",
               "-H", "Authorization: Bearer YOUR_PORTWING_TOKEN",
               "http://your-host:3000/_portwing/mcp"],
      "type": "http",
      "url": "http://your-host:3000/_portwing/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PORTWING_TOKEN"
      }
    }
  }
}

Add via claude mcp add (CLI)

claude mcp add --transport http \
  --header "Authorization: Bearer YOUR_PORTWING_TOKEN" \
  portwing http://your-host:3000/_portwing/mcp

.mcp.json (project-level, Cursor / Windsurf / any client)

{
  "mcpServers": {
    "portwing": {
      "type": "http",
      "url": "http://your-host:3000/_portwing/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PORTWING_TOKEN"
      }
    }
  }
}

Replace YOUR_PORTWING_TOKEN with the value you set in TOKEN / TOKEN_FILE / TOKEN_HASH.

Drydock-Compatible Endpoints

Docker API Proxy

All other paths (/*) are transparently proxied to the Docker Engine API, including streaming endpoints and exec session hijacking.

Metrics

Portwing exposes Prometheus metrics at /_portwing/metrics (and the alias /metrics). Both require bearer auth. In addition to build/host/per-container series, both endpoints also expose agent request metrics: portwing_http_requests_total{method,code}, portwing_http_request_duration_seconds (histogram), portwing_http_requests_in_flight (gauge), portwing_auth_failures_total{reason}, and portwing_rate_limited_total.

Prometheus scrape config:

scrape_configs:
  - job_name: portwing
    scheme: https          # or http if TLS not configured
    static_configs:
      - targets: ["your-host:3000"]
    authorization:
      type: Bearer
      credentials: YOUR_PORTWING_TOKEN
    tls_config:
      # ca_file: /etc/prometheus/portwing-ca.crt  # if using custom CA
      insecure_skip_verify: false

Plaintext token (testing only)

Warning: Environment variables are visible in docker inspect and process listings. For production, use TOKEN_FILE or TOKEN_HASH_FILE with a mounted secret.

# Generate a strong token
TOKEN=$(openssl rand -hex 32)
docker run -e TOKEN="$TOKEN" ... ghcr.io/codeswhat/portwing:latest

File-based token (production)

TOKEN=$(openssl rand -hex 32)
printf '%s' "$TOKEN" > /run/secrets/portwing-token
chmod 600 /run/secrets/portwing-token
docker run -e TOKEN_FILE=/run/secrets/portwing-token \
  -v /run/secrets/portwing-token:/run/secrets/portwing-token:ro \
  ... ghcr.io/codeswhat/portwing:latest

Hash-at-rest with TOKEN_HASH

Store only an Argon2id hash so the plaintext token never appears in env dumps or config files:

# Generate the hash (token is read from stdin, never argv)
HASH=$(printf '%s' "$TOKEN" | portwing hash-token)
# $argon2id$v=19$m=19456,t=2,p=1$<salt>$<hash>

# Use the hash instead of the plaintext
docker run -e TOKEN_HASH="$HASH" ... ghcr.io/codeswhat/portwing:latest

Or write the hash to a file and use TOKEN_HASH_FILE:

printf '%s' "$TOKEN" | portwing hash-token > /run/secrets/portwing-token-hash
docker run -e TOKEN_HASH_FILE=/run/secrets/portwing-token-hash ...

Portwing releases are signed with Sigstore cosign via GitHub Actions keyless signing. Checksums and container images can be verified without managing signing keys.

Verify the checksums file

TAG=v0.1.0

cosign verify-blob \
  --certificate-identity-regexp "https://github.com/CodesWhat/portwing/.github/workflows/.*" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  --bundle "checksums.txt.bundle" \
  "checksums.txt"

Verify the container image

TAG=v0.1.0

cosign verify \
  --certificate-identity-regexp "https://github.com/CodesWhat/portwing/.github/workflows/.*" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  "ghcr.io/codeswhat/portwing:${TAG}"

SBOM

Each release includes a CycloneDX SBOM attached as a release asset (portwing-${TAG}-sbom.cdx.json). Download and inspect it with any CycloneDX-compatible tool, or verify it with cosign the same way as the checksums file.

• Authentication: Token-based with timing-safe comparison (crypto/subtle); hash-at-rest via TOKEN_HASH (Argon2id); Ed25519 per-client keypairs with per-request signatures and replay protection
• Rate Limiting: 10 failed auth attempts per IP per minute
• TLS: TLS 1.2+ with modern AEAD cipher suites
• Compose Security: Path traversal protection, env var denylist, service name injection prevention
• Resource Limits: WebSocket (16 MB), response body (100 MB), exec sessions (100 concurrent)

See docs/security-model.md for the full citable spec and CVE mapping.

Portwing ships structured JSON audit logging for every security-relevant action — a feature that commercial container management platforms lock behind paid tiers.

Enable

# Write to a file (opened append-only, mode 0600)
docker run -e AUDIT_LOG=/var/log/portwing-audit.log ...

# Or to stdout/stderr (useful with log aggregators)
docker run -e AUDIT_LOG=stdout ...

Auditing is disabled by default (AUDIT_LOG unset). When disabled the overhead is a single nil pointer check per request. Separately, setting AUDIT_BUFFER_SIZE (default 256) keeps the most recent audit records in an in-memory ring buffer for pull-based retrieval at GET /_portwing/audit (auth required), so a controller can read the audit trail without host file access. The buffer is independent of AUDIT_LOG and works even when the slog sink is off.

Events

Sample JSON lines

{"time":"2026-01-15T10:23:45.123456789Z","level":"INFO","msg":"","event":"api_request","actor":"203.0.113.42","method":"POST","path":"/_portwing/compose","outcome":"allowed","status":200,"duration_ms":3.14}

Compose operations include additional fields:

{"time":"2026-01-15T10:23:45.200Z","level":"INFO","msg":"","event":"compose_op","actor":"203.0.113.42","operation":"up","stack":"nginx-stack","outcome":"allowed"}

Exec tunnel events:

{"time":"2026-01-15T10:24:01.500Z","level":"INFO","msg":"","event":"exec_start","actor":"203.0.113.42","container":"abc123def456","exec_id":"e7f8a9b1","outcome":"allowed"}