How to configure and mount a remote host

[pavlis12-lab]

Hello,

I am trying to connect a remote host (agent) to the main drydock controller but I had no success.

The documentation is not straightforward.

Can someone explain the process and the steps to set it up?

[scttbnsn]

Mental model

In the standard setup, the controller dials out to each agent. The agent is a passive HTTP server; it has no idea where the controller lives and doesn't need to. You put DD_AGENT_{name}_HOST on the controller, not on the agent. The agent just needs its port open and reachable from wherever the controller runs.

One thing worth knowing: there's an experimental edge mode (DD_EXPERIMENTAL_PORTWING=true on the controller) where the agent dials the controller over WebSocket instead. That's useful if the agent is behind NAT or a firewall and you can't open an inbound port. It uses a different auth model (Ed25519 key pairs, not a shared secret) and isn't in the main agents docs yet. Everything below is for the standard SSE mode, which is what you're almost certainly using.

---

Minimal config to get connected

Agent machine (on the remote host):

services:
  drydock-agent:
    image: codeswhat/drydock
    command: --agent
    ports:
      - "3000:3000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - DD_AGENT_SECRET=pick-a-long-random-string
      - DD_WATCHER_LOCAL_SOCKET=/var/run/docker.sock

Controller machine:

services:
  drydock:
    image: codeswhat/drydock
    ports:
      - "3000:3000"
    environment:
      - DD_LOCAL_WATCHER=false                         # pure aggregator, skip local watcher
      - DD_AGENT_REMOTE1_HOST=192.168.1.50
      - DD_AGENT_REMOTE1_SECRET=pick-a-long-random-string  # must match agent DD_AGENT_SECRET

REMOTE1 is a label you choose. It shows up in logs and the UI as remote1 (lowercased by the config parser). DD_AGENT_REMOTE1_PORT is optional and defaults to 3000.

A docker trigger (DD_ACTION_DOCKER_*) is not needed just to monitor. It's only required if you want to trigger container updates from the UI or API.

---

The three gotchas that actually bite people

1. Plain HTTP + a secret = startup error, not a warning.

The controller throws on startup when a secret is configured over HTTP:

Error: Agent remote1 is configured with a secret over insecure HTTP (http://192.168.1.50:3000). Configure HTTPS (certfile/cafile) to protect X-Dd-Agent-Secret.

On a private LAN, add DD_AGENT_ALLOW_INSECURE_SECRET=true on the controller to allow it (demoted to a warn log). For production, terminate TLS in front of the agent or set DD_AGENT_REMOTE1_CAFILE/CERTFILE/KEYFILE on the controller.

2. Forgetting command: --agent is silent.

Without command: --agent, the container starts as a controller. It won't enforce DD_AGENT_SECRET on incoming requests. The result looks like a network problem from the controller side (repeated 401s), not a misconfigured agent.

3. Missing DD_AGENT_SECRET crashes the agent at startup.

The agent won't start at all if neither DD_AGENT_SECRET nor DD_AGENT_SECRET_FILE is set. It throws immediately on boot, so docker logs drydock-agent will show the error right at the top.

---

Log checklist: what to look for

On the controller (docker logs drydock):

What you see	What it means
Connecting to agent remote1 at http://192.168.1.50:3000	Controller is attempting to connect
Handshake successful. Received N containers.	Working
Agent remote1 is configured with a secret over insecure HTTP... (startup Error)	Add TLS or set DD_AGENT_ALLOW_INSECURE_SECRET=true
SSE Connection failed: Request failed with status code 401. Retrying...	Secret mismatch between DD_AGENT_SECRET and DD_AGENT_REMOTE1_SECRET
SSE Connection failed: connect ECONNREFUSED 192.168.1.50:3000. Retrying...	Agent not running or port 3000 not published/reachable
SSE Connection failed: connect ETIMEDOUT 192.168.1.50:3000. Retrying...	Firewall or NAT blocking the path

On the agent (docker logs drydock-agent): look for a startup error about DD_AGENT_SECRET if the agent won't respond at all, or for the watcher initialization log confirming it connected to the Docker socket.

The controller retries with backoff (up to 60s between attempts) so connection errors repeat in the log until the agent is healthy.

If you're still stuck, paste your controller logs (the lines starting with agent-client) and I'll point at the exact issue.

[pavlis12-lab]

Thank you. I think now is more clear of what to do.

I thing the error was related to the connection not been HTTPS and the controller was restarting continuously.

So as I understand I need to add to the controller YML DD_AGENT_ALLOW_INSECURE_SECRET=true to bypass this error?

[scttbnsn]

Yes, exactly. That error was the crash loop. The controller throws on startup when an agent has a secret configured but the URL is plain HTTP, and Docker just keeps restarting the container. Adding DD_AGENT_ALLOW_INSECURE_SECRET=true on the controller turns that hard error into a warning and lets it boot.

One thing to know before you set it: it doesn't make the connection secure, it just stops drydock from refusing to run. The secret still travels in cleartext in the X-Dd-Agent-Secret header, so anyone who can see traffic between the controller and the agent can read it. On a trusted home/private LAN that's usually a fine tradeoff. If that controller→agent path ever crosses an untrusted network, set up TLS instead:

• terminate TLS in front of the agent (a reverse proxy with a cert), or
• point the controller at the agent over HTTPS and give it the cert with DD_AGENT_REMOTE1_CAFILE (add CERTFILE/KEYFILE for mutual TLS). Setting CAFILE or CERTFILE, or using port 443, auto-switches the controller to HTTPS and you won't need the insecure flag at all.

Nothing else in your config needs to change for this. Host and a matching secret are the only other required bits, and the throw was purely about HTTP-plus-secret. Drop the flag in, restart the controller, and you should see Handshake successful. Received N containers. in docker logs. If it still doesn't connect, paste the controller logs (the agent-client lines) and I'll take a look.