Hawser Agent - Dockhand

Hawser is Dockhand’s lightweight agent that enables secure connections to Docker hosts in edge locations, behind NAT, or within private networks. It establishes outbound WebSocket connections to your Dockhand server, eliminating the need for port forwarding or VPN configuration.

Overview

Hawser provides two connection modes:

Standard Mode

Direct HTTP/HTTPS connection with token authentication. Use for hosts accessible via direct TCP.

Edge Mode

WebSocket-based connection for NAT traversal. Perfect for edge devices, home labs, and private networks.

Architecture

Standard Mode

In Standard mode, Hawser acts as a reverse proxy, forwarding authenticated requests to the local Docker daemon.

Edge Mode

In Edge mode, Hawser establishes an outbound WebSocket connection, enabling bidirectional communication without inbound ports.

Installation

Hawser is distributed as a single binary for Linux, macOS, and Windows.

Docker
Linux
macOS
Windows

Run Hawser as a container:

docker run -d \
  --name hawser \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e DOCKHAND_SERVER_URL=https://dockhand.example.com \
  -e DOCKHAND_TOKEN=your-token-here \
  ghcr.io/dockhand/hawser:latest

Download and install the binary:

# Download latest release
curl -fsSL https://github.com/dockhand/hawser/releases/latest/download/hawser-linux-amd64 -o hawser
chmod +x hawser
sudo mv hawser /usr/local/bin/

# Create systemd service
sudo tee /etc/systemd/system/hawser.service > /dev/null <<EOF
[Unit]
Description=Hawser Edge Agent
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
Environment="DOCKHAND_SERVER_URL=https://dockhand.example.com"
Environment="DOCKHAND_TOKEN=your-token-here"
ExecStart=/usr/local/bin/hawser
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Start the service
sudo systemctl daemon-reload
sudo systemctl enable hawser
sudo systemctl start hawser

Download and install:

# Download latest release
curl -fsSL https://github.com/dockhand/hawser/releases/latest/download/hawser-darwin-amd64 -o hawser
chmod +x hawser
sudo mv hawser /usr/local/bin/

# Run with environment variables
export DOCKHAND_SERVER_URL=https://dockhand.example.com
export DOCKHAND_TOKEN=your-token-here
hawser

Download from GitHub releases and run:

# Set environment variables
$env:DOCKHAND_SERVER_URL="https://dockhand.example.com"
$env:DOCKHAND_TOKEN="your-token-here"

# Run Hawser
.\hawser.exe

Configuration

Generating Tokens

Create environment

In Dockhand, navigate to Settings > Environments and create a new environment.

Select Hawser mode

Choose connection type:

Hawser Standard: For direct HTTP access
Hawser Edge: For WebSocket connections (recommended)

Generate token

Click Generate Token. The token will only be shown once, so save it securely.

Configure agent

Set the token on your Hawser agent:

export DOCKHAND_TOKEN=dh_xxxxxxxxxxxxxxxxx

Environment Variables

# Required
DOCKHAND_SERVER_URL=https://dockhand.example.com  # Dockhand server URL
DOCKHAND_TOKEN=dh_xxxxxxxxxx                     # Authentication token

# Optional
DOCKER_HOST=unix:///var/run/docker.sock          # Docker socket path
HAWSER_MODE=edge                                  # 'standard' or 'edge' (default: edge)
HAWSER_PORT=8080                                  # Port for standard mode (default: 8080)
HAWSER_AGENT_NAME=production-01                   # Custom agent name
LOG_LEVEL=info                                    # Logging level (debug|info|warn|error)

Standard Mode Configuration

For Standard mode, configure the agent to listen on a port:

export HAWSER_MODE=standard
export HAWSER_PORT=8080
export DOCKHAND_TOKEN=dh_xxxxxxxxxx
hawser

Then configure the environment in Dockhand:

Name: Remote Server
Connection Type: Hawser Standard
Host: hawser.example.com
Port: 8080
Protocol: https
Token: (configured automatically)

WebSocket Protocol

Hawser Edge uses a JSON-based WebSocket protocol for bidirectional communication.

Message Types

hello

Sent by agent on connection:

{
  "type": "hello",
  "version": "1.0",
  "agentId": "uuid",
  "agentName": "production-01",
  "token": "dh_xxxxxxxxxx",
  "dockerVersion": "24.0.7",
  "hostname": "docker-host",
  "capabilities": ["compose", "exec", "metrics"]
}

welcome

Sent by server after authentication:

{
  "type": "welcome",
  "environmentId": 1,
  "serverId": "dockhand",
  "version": "1.0"
}

request

Docker API request from server:

{
  "type": "request",
  "requestId": "uuid",
  "method": "GET",
  "path": "/containers/json",
  "headers": {},
  "body": null,
  "streaming": false
}

response

Response from agent:

{
  "type": "response",
  "requestId": "uuid",
  "statusCode": 200,
  "headers": {"Content-Type": "application/json"},
  "body": "[...]",
  "isBinary": false
}

metrics

System metrics from agent:

{
  "type": "metrics",
  "timestamp": 1234567890,
  "metrics": {
    "cpuUsage": 45.2,
    "cpuCores": 8,
    "memoryTotal": 16000000000,
    "memoryUsed": 8000000000,
    "uptime": 3600
  }
}

ping/pong

Heartbeat messages:

{"type": "ping", "timestamp": 1234567890}
{"type": "pong", "timestamp": 1234567890}

Features

Automatic Reconnection

Hawser automatically reconnects to the Dockhand server if the connection is lost. It uses exponential backoff to avoid overwhelming the server:

Initial retry: 1 second
Maximum retry interval: 60 seconds
Backoff multiplier: 2x

Container Event Forwarding

Hawser monitors Docker events and forwards them to Dockhand in real-time:

{
  "type": "container_event",
  "event": {
    "containerId": "abc123",
    "containerName": "nginx",
    "image": "nginx:latest",
    "action": "start",
    "timestamp": "2024-03-04T12:00:00Z"
  }
}

Metrics Collection

Hawser collects and reports host metrics every 30 seconds:

CPU usage (per core and total)
Memory usage (used/total)
Disk usage
Network I/O
Uptime

Docker Compose Support

Hawser supports Docker Compose operations through a special endpoint:

POST /_hawser/compose
{
  "command": "up",
  "composeFile": "version: '3.8'\nservices:\n  app:\n    image: nginx",
  "envFile": "KEY=value",
  "project": "myapp"
}

Monitoring

Connection Status

View active Hawser connections in Dockhand:

Navigate to Settings > Environments
Check the Status column for connected agents
Click View Details to see:
- Agent version
- Docker version
- Last seen timestamp
- Uptime
- Capabilities

Health Check Endpoint

In Standard mode, Hawser exposes a health check endpoint:

curl http://localhost:8080/health

Response:

{
  "status": "healthy",
  "docker": "connected",
  "version": "1.0.0"
}

Troubleshooting

Agent won't connect

Verify DOCKHAND_SERVER_URL is correct and reachable
Check token is valid and not expired
Ensure firewall allows outbound WebSocket connections (port 443 for HTTPS)
Review agent logs: journalctl -u hawser -f
Test connectivity: curl https://dockhand.example.com/api/hawser/connect

Connection keeps dropping

Check network stability between agent and server
Verify no proxy or load balancer is terminating WebSocket connections
Increase WebSocket timeout on reverse proxy if applicable
Review server logs for error messages

Docker commands fail

Verify Docker socket path is correct (DOCKER_HOST)
Ensure Hawser has permission to access Docker socket
For containers, mount socket: -v /var/run/docker.sock:/var/run/docker.sock
Check Docker daemon is running: docker ps

Metrics not appearing

Verify agent capabilities include “metrics”
Check agent logs for metric collection errors
Ensure agent has permission to read system metrics
Metrics are reported every 30 seconds, wait for next interval

Security Considerations

Hawser tokens provide full access to the Docker daemon. Treat them like root passwords.

Token rotation: Regenerate tokens periodically (every 90 days)
Network security: Use HTTPS for server URL (enforces TLS for WebSocket)
Access control: Create separate environments/tokens for different hosts
Monitoring: Enable audit logging to track all Docker API calls
Minimal privileges: Run Hawser with minimal required permissions

Advanced Configuration

Custom Docker Socket

For non-standard Docker installations:

export DOCKER_HOST=tcp://localhost:2375
# or
export DOCKER_HOST=unix:///custom/path/docker.sock

Behind Corporate Proxy

Configure HTTP proxy for WebSocket connections:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

Custom CA Certificates

For self-signed certificates:

export SSL_CERT_FILE=/path/to/ca-bundle.crt
# or
export SSL_CERT_DIR=/path/to/certs/

API Reference

For detailed API information, see:

Token Management: /api/hawser/tokens
Connection Status: /api/hawser/connect
WebSocket Endpoint: wss://your-server/api/hawser/connect

See the API Reference for full documentation.

Next Steps

Remote Hosts

Configure direct TLS connections

Webhooks

Set up Git webhooks for automatic deployments

Documentation Index

​Overview

Standard Mode

Edge Mode

​Architecture

​Standard Mode

​Edge Mode

​Installation

​Configuration

​Generating Tokens

​Environment Variables

​Standard Mode Configuration

​WebSocket Protocol

​Message Types

​Features

​Automatic Reconnection

​Container Event Forwarding

​Metrics Collection

​Docker Compose Support

​Monitoring

​Connection Status

​Health Check Endpoint

​Troubleshooting

​Security Considerations

​Advanced Configuration

​Custom Docker Socket

​Behind Corporate Proxy

​Custom CA Certificates

​API Reference

​Next Steps

Remote Hosts

Webhooks

Overview

Architecture

Standard Mode

Edge Mode

Installation

Configuration

Generating Tokens

Environment Variables

Standard Mode Configuration

WebSocket Protocol

Message Types

Features

Automatic Reconnection

Container Event Forwarding

Metrics Collection

Docker Compose Support

Monitoring

Connection Status

Health Check Endpoint

Troubleshooting

Security Considerations

Advanced Configuration

Custom Docker Socket

Behind Corporate Proxy

Custom CA Certificates

API Reference

Next Steps