Drydock Integration

Portwing is designed to be a drop-in replacement for the original Drydock Node.js agent. It speaks the same REST and SSE protocol that Drydock's AgentClient expects, and adds an outbound WebSocket path (Edge Mode) for NAT/firewall-constrained hosts.

Architecture

Drydock supports two agent connectivity patterns. Portwing implements both.

Standard Mode (fully implemented): The Drydock controller opens an inbound HTTP connection to each remote host's Portwing agent. Portwing runs an HTTP server; the controller polls /api/* and holds a long-lived SSE stream.

Edge Mode (stable portwing/1.0): Portwing dials outbound to the Drydock controller's /api/portwing/ws WebSocket endpoint. All communication is multiplexed over the single connection. This works behind NAT and dynamic IPs.

Standard Mode: Handshake Sequence

Verified against Drydock v1.6.0-rc.11+ (app/agent/AgentClient.ts).

When a Drydock controller connects to a Portwing agent in Standard Mode, the following sequence occurs:

1. The controller opens GET /api/events with the X-Dd-Agent-Secret header. Portwing responds with a text/event-stream.
2. Portwing immediately emits dd:ack on the stream. The controller's handleAckEvent() triggers handshake().
3. The controller calls GET /api/containers, then GET /api/watchers, then GET /api/triggers in sequence.
4. The SSE stream remains open. Portwing pushes dd:container-added, dd:container-updated, and dd:container-removed events as container state changes.
5. After every poll cycle, Portwing also emits dd:watcher-snapshot so the controller can prune any stale entries. A reconnecting controller receives the current snapshot immediately after dd:ack — no waiting for the next poll interval.

Endpoints Portwing Serves (Standard Mode)

All /api/* endpoints require an X-Dd-Agent-Secret or X-Portwing-Token header. The /health endpoint is unauthenticated.

SSE Event Shapes

Drydock parses SSE frames as data: <json>\n\n. Each frame is a JSON object with type and data fields (AgentClient.ts:659).

dd:ack

Sent on every new SSE connection. Drydock reads version, os, arch, cpus, memoryGb, uptimeSeconds, lastSeen, logLevel, and pollInterval from the payload.

{
  "type": "dd:ack",
  "data": {
    "version": "0.9.0",
    "os": "linux",
    "arch": "amd64",
    "cpus": 4,
    "memoryGb": 15.6,
    "uptimeSeconds": 123,
    "lastSeen": "2026-06-11T12:00:00Z",
    "logLevel": "info",
    "pollInterval": "5m0s",
    "containers": {"total": 3, "running": 2, "stopped": 1},
    "images": 2
  }
}

dd:container-added / dd:container-updated

{"type": "dd:container-added", "data": {}}

The data field is a full Container object (see Container Object Shape below).

dd:container-removed

Drydock reads only .data.id from this event. Portwing also sends name as a harmless extra field.

{"type": "dd:container-removed", "data": {"id": "abc123", "name": "web"}}

dd:watcher-snapshot

Sent after every container poll cycle and immediately after dd:ack to each newly connected SSE client. Drydock uses this event to prune stale containers — containers absent from the snapshot are removed from the controller's store.

{
  "type": "dd:watcher-snapshot",
  "data": {
    "watcher": {"type": "docker", "name": "docker", "configuration": {}},
    "containers": []
  }
}

Container Object Shape

Portwing's GET /api/containers and all container events return objects in this shape. Drydock passes them directly to storeContainer.insertContainer() / storeContainer.updateContainer().

Drydock Container Labels

Portwing reads dd.* labels from Docker containers to populate the Container object and configure watcher behaviour.

Watcher Component Descriptor Shape

GET /api/watchers returns an array; GET /api/watchers/{type}/{name} returns a single descriptor.

Drydock reads type, name, configuration, and metadata from each descriptor.

[{
  "type": "docker",
  "name": "docker",
  "configuration": {
    "description": "Watches Docker containers for updates via Docker Engine API",
    "capabilities": ["container-sync", "labels"],
    "transport": "docker-api",
    "execution": "controller",
    "events": "portwing"
  }
}]

Watcher Delegation Model

The watcher descriptor declares transport: "docker-api", execution: "controller", and events: "portwing". Together these fields define the integration contract:

1. A compatible Drydock controller runs its native Docker watcher and update trigger controller-side.
2. Docker inspection and update calls traverse Portwing's authenticated, transparent proxy: inbound HTTP in Standard Mode or correlated request/response messages over the outbound WebSocket in Edge Mode.
3. Portwing reports inventory, reads dd.* labels, and emits Docker lifecycle events. events: "portwing" prevents Drydock from opening a second Docker event stream through the proxy.
4. Drydock records the watcher result and owns update orchestration and update operation events.

updateAvailable is always false and updateKind is always "unknown" in Portwing's raw inventory. That metadata is not ignored: Drydock enriches its controller-side result after running the native watcher through Portwing.

Portwing advertises no remote trigger: GET /api/triggers, edge triggerTypes, and the trigger portion of component sync remain empty. The dd:trigger protocol vocabulary is retained for wire compatibility, but the watcher and trigger POST endpoints continue to return 501 for older clients.

Edge Mode: WebSocket Handshake

When DRYDOCK_URL is set, Portwing dials outbound to DRYDOCK_URL/api/portwing/ws and sends portwing/1.0 as the protocol identifier inside its hello message — an application-level field, not a negotiated Sec-WebSocket-Protocol sub-protocol header.

Handshake sequence:

1. Portwing connects via WSS to /api/portwing/ws.
2. Portwing sends a hello message (see payload below).
3. Controller responds with welcome containing the poll interval.
4. Portwing sends dd:component_sync (watcher/trigger descriptors) before dd:container_sync (full container inventory), then sends an initial metrics payload. The ordering lets Drydock establish controller-owned update state before it ingests Portwing's raw inventory.

hello Message

{
  "type": "hello",
  "data": {
    "version": "1.0.0",
    "protocol": "portwing/1.0",
    "agentId": "uuid",
    "agentName": "my-server",
    "pubKeyId": "a3f2b1c9d8e7f6a4",
    "timestamp": 1749820800,
    "nonce": "0123456789abcdef0123456789abcdef",
    "signature": "<base64url-ed25519-signature>",
    "dockerVersion": "27.0.3",
    "hostname": "my-server",
    "capabilities": [
      "compose", "exec", "metrics", "events",
      "dd:container-sync", "dd:logs"
    ],
    "drydockCompat": "1.4.0",
    "watcherTypes": ["docker"],
    "triggerTypes": []
  }
}

All Edge Mode JSON application messages are wrapped in an Envelope ({"type": ..., "data": ...}, internal/protocol/messages.go) — the fields above live under data, not at the top level. (WebSocket ping/pong/close control frames are not wrapped.)

When PRIVATE_KEY_FILE is set, the hello carries the pubKeyId, timestamp, nonce, and signature fields shown above, and Drydock verifies the signature against the agent's registered public key. The tokenHash field (SHA-256 of the shared token) is only a fallback for non-edge endpoints — the Drydock /api/portwing/ws endpoint rejects token-hash hellos with ed25519-required.

Edge Mode Message Types

Core protocol:

Exec (interactive docker exec sessions):

If a session fails to start (for example, a sockguard exec-policy denial), the agent's failStart path sends exec_end immediately instead of exec_ready. Its reason field now carries the underlying Docker/sockguard error body — e.g. not allowed by portwing preset or exec denied: privileged exec is not allowed — rather than a bare status code. Drydock's edge agent adapter does not yet surface that reason to the user; today it receives the frame but discards reason before it reaches Drydock's own exec error display.

Drydock-specific (dd: namespace):

For continuous logs, Drydock sends stream:true with a mandatory requestId. Portwing emits separate stdout/stderr chunks and then an end or error frame. Closing the browser viewer sends dd:container_log_cancel, which cancels the Docker request promptly. Portwing admits at most 128 live log streams and uses the edge connection's bounded send queue; Drydock caps each downstream viewer at 1 MiB. A stalled consumer is disconnected instead of growing memory without limit.

Mixed-version fleets degrade gracefully. An older agent ignores stream and returns dd:container_log_response; Drydock renders it as one stdout chunk and ends the viewer. Requests without stream:true retain the bounded one-shot response. Docker's 8-byte stream headers are removed and converted into the chunk's stream field; a TTY container's raw stream is emitted as stdout.

A hello rejection is classified before the agent reconnects. Terminal codes (ed25519-required, unknown-key, bad-signature, protocol-mismatch, no-auth, invalid-agent-name, parse-error, expected-hello, agent-name-claimed) stop the agent with an actionable error instead of retrying forever; timing/capacity codes (timestamp-skew, replay, rate-limited, registry-full, agent-already-connected, …) and any unrecognized code are retried with backoff.

Environment Variable Reference

Portwing Side (agent)

For the full variable reference including Docker socket, metrics, and reconnect settings, see Configuration.

Drydock Controller Side

These are set in Drydock's agent component configuration, not environment variables on the Portwing host.

Deploying for Standard Mode

Docker Compose (agent host)

services:
  portwing:
    image: ghcr.io/codeswhat/portwing:latest
    environment:
      TOKEN: "${DD_AGENT_SECRET}"
      PORT: "3000"
      AGENT_NAME: "my-server"
    # The image runs as non-root UID 65532; grant the Docker socket's group:
    #   export DOCKER_SOCK_GID=$(stat -c '%g' /var/run/docker.sock)
    group_add:
      - "${DOCKER_SOCK_GID:?set to the GID of /var/run/docker.sock}"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "3000:3000"
    restart: unless-stopped

Drydock Agent Component Configuration (controller)

agent:
  my-server:
    host: http://my-server-ip
    port: 3000
    secret: "${DD_AGENT_SECRET}"

The TOKEN value on the Portwing side must match the secret value on the Drydock side.

Compatibility Matrix

Verified against Drydock v1.6.0-rc.11+ (app/agent/AgentClient.ts, app/agent/api/).

Related Pages

• Connection Modes — Standard vs Edge Mode detection and configuration
• Authentication — Shared secret, token hash, and Ed25519 key auth
• Configuration — Full environment variable reference
• Drydock repository — Controller source