DockPal Agent

Lightweight Docker proxy + host reporter for DockPal multi-instance management.

The agent runs on each managed host and exposes the Docker daemon and host info to the DockPal Server over a secure channel. It has no UI, no database, no templates, no Traefik config, no tunnel management, no self-update.

Quick Start

The image is published to GitHub Container Registry: ghcr.io/sdldev/dockpal-agent.

Direct Mode (host with public IP)

docker run -d \
  --name dockpal-agent \
  --restart unless-stopped \
  -e DOCKPAL_MODE=direct \
  -e DOCKPAL_TOKEN=agt-YOUR_TOKEN_HERE \
  -p 9273:9273 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/dockpal-agent:/opt/dockpal-agent \
  ghcr.io/sdldev/dockpal-agent:latest

The /opt/dockpal-agent mount persists compose files and the auto-generated TLS certificate across restarts.

Edge Mode (host behind NAT)

docker run -d \
  --name dockpal-agent \
  --restart unless-stopped \
  -e DOCKPAL_MODE=edge \
  -e DOCKPAL_EDGE_SERVER=wss://dockpal.example.com:3012 \
  -e DOCKPAL_TOKEN=agt-YOUR_TOKEN_HERE \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/dockpal-agent:/opt/dockpal-agent \
  ghcr.io/sdldev/dockpal-agent:latest

Note: Edge mode does not publish any port. The agent makes an outbound connection only.

Environment Variables

Variable	Required	Default	Description
DOCKPAL_MODE	yes	—	direct or edge
DOCKPAL_TOKEN	yes	—	Enrollment token from Server
DOCKPAL_DIRECT_LISTEN	no	:9273	Listen address (direct mode)
DOCKPAL_DIRECT_TLS	no	true	Enable TLS (direct mode)
DOCKPAL_TLS_CERT_DIR	no	/opt/dockpal-agent/certs	Directory for TLS certs (auto-generated if missing)
DOCKPAL_EDGE_SERVER	edge only	—	Server URL, e.g. wss://dockpal.example.com:3012
DOCKPAL_EDGE_RECONNECT	no	5s	Reconnect interval on disconnect
DOCKPAL_EDGE_HEARTBEAT	no	30s	Heartbeat ping interval
DOCKPAL_DOCKER_SOCKET	no	/var/run/docker.sock	Docker daemon socket path

API Reference

All endpoints require Authorization: Bearer <token> (except /agent/ping).

Unauthenticated

Method	Path	Description
GET	/agent/ping	Liveness check (for Docker HEALTHCHECK)

Authenticated

Method	Path	Description
POST	/agent/enroll	Enrollment handshake
GET	/agent/host/info	Static host info (OS, CPU, RAM, Docker version)
GET	/agent/host/stats	Real-time host stats (CPU, RAM, disk)
GET	/agent/docker/containers	List containers
GET	/agent/docker/containers/:id	Inspect container
POST	/agent/docker/containers/:id/start	Start container
POST	/agent/docker/containers/:id/stop	Stop container
POST	/agent/docker/containers/:id/restart	Restart container
DELETE	/agent/docker/containers/:id	Remove container
PUT	/agent/docker/containers/:id	Edit container
GET	/agent/docker/containers/:id/stats	Container stats
GET	/agent/docker/containers/:id/logs	Container logs (WebSocket)
GET	/agent/docker/containers/:id/stats/ws	Stats stream (WebSocket)
POST	/agent/docker/deploy/compose	Deploy compose
POST	/agent/docker/deploy/stream	Deploy compose (streamed)
POST	/agent/docker/compose/stop	Stop compose project
POST	/agent/docker/compose/remove	Remove compose project
GET	/agent/docker/images	List images
POST	/agent/docker/images/pull	Pull image
DELETE	/agent/docker/images/:id	Remove image
GET	/agent/docker/files	List files
GET	/agent/docker/files/read	Read file
POST	/agent/docker/files/write	Write file
POST	/agent/docker/files/upload	Upload file
GET	/agent/docker/files/download	Download file
DELETE	/agent/docker/files	Delete file
POST	/agent/docker/containers/:id/files/write	Write container file

Building from Source

# Build binary
go build -o dockpal-agent .

# Build Docker image — requires buildx
docker buildx build \
  --platform linux/amd64 \
  --build-arg VERSION=dev \
  -t ghcr.io/sdldev/dockpal-agent:latest .

Security Notes

• The agent token is stored in plaintext in the agent's environment variable. This is acceptable because the token is a random 32-byte value, not a user-chosen password.
• Direct mode auto-generates a self-signed TLS certificate (ECDSA P-256, 365-day validity).
• Registry credentials are never stored on the agent. They are delivered on-demand from the Server and discarded after use.
• File paths are validated to prevent path traversal attacks.

Troubleshooting

• Docker socket not mounted: Ensure -v /var/run/docker.sock:/var/run/docker.sock is in the docker run command.
• Token mismatch: Verify the token matches the one generated by the DockPal Server when the instance was created.
• TLS errors: The Server's DirectClient must accept self-signed certs. For MVP, InsecureSkipVerify is used.
• Edge mode not connecting: Check that DOCKPAL_EDGE_SERVER is correct and the Server is reachable from the agent host.

Design Constraints

Constraint	Target
Binary size	< 10 MB
Idle RAM	< 20 MB
Dependencies	Go 1.25, Docker SDK, Gin, Gorilla WebSocket
Deployment	Docker container (primary), systemd binary (secondary)
Network	Direct mode: listen on port; Edge mode: outbound WebSocket only