Skip to content

Connecting a Remote Docker Host

Your HomeLab is in the basement. Charon is running somewhere else — maybe on a cloud server, maybe in your office. This guide connects them safely, without opening any ports on your HomeLab or touching your router.

By the end, Charon will list your remote machine's Docker containers just like local ones, and you can route websites to them with a single click.


Before You Start

Make sure you have:

  • [ ] Charon is running and you can log in
  • [ ] The remote machine (HomeLab) has Docker installed
  • [ ] The remote machine can reach the internet (standard outbound HTTPS on port 443)
  • [ ] You can run commands on the remote machine — via SSH, a keyboard, or a terminal app

Same server as Charon? Orthrus works there too and is the recommended way to avoid mounting the Docker socket into Charon. Follow the steps below, then see Using Orthrus on the same server as Charon for which server address to use.


Step 1 — Register an Agent in Charon

  1. In the Charon sidebar, open Hecate → Agent (admins only)
  2. Click Add Agent
  3. Type a name for this machine — something like "HomeLab" or "NAS Box"
  4. Click Create

⚠️ Copy the auth key before closing this screen. It starts with ch_orthrus_ and is shown one time only. Paste it into a note or your password manager immediately. If you lose it, you'll need to delete the agent and start over.


Step 2 — Install the Agent on Your Remote Machine

Still in Charon, click the Install tab on the agent page. You'll see two ready-made snippets: Docker Compose and Kubernetes. Docker Compose is the easiest if your remote machine already runs Docker.

On your remote machine, open a terminal and:

  1. Create a new folder for the agent: mkdir orthrus-agent && cd orthrus-agent
  2. Copy the Docker Compose snippet from the Charon UI
  3. Create a file called docker-compose.yml and paste the snippet into it
  4. Save your key to a file. The first lines of the snippet show a command that does this. Replace <AUTH_KEY> with the key you saved in Step 1, then run that command in the same folder. It creates a file named orthrus_auth_key. Your key stays in that file and is not written into docker-compose.yml. See Keep the Auth Key in a File.
  5. Check the permission settings. The file should include PUID, PGID, and TZ lines. Set PGID to your Docker group's number: run stat -c '%g' /var/run/docker.sock on the remote machine and put the number it prints after PGID=. Most setups need this. See Set the Permissions for details.

Heads up: That number goes in PGID only. DOCKER_SOCK stays the socket's path (/var/run/docker.sock); do not build it from the number. To check it, run getent group <number>; it should print the docker group.

Using rootless Docker? The settings are different. See Rootless Docker. 6. Run:

docker compose up -d

The agent starts in the background and immediately tries to connect to Charon.

Using Kubernetes? The Install tab's Kubernetes snippet starts with a command that stores your key in a Kubernetes Secret. Run that command first, then apply the rest of the snippet.


Step 3 — Verify the Agent Is Online

Switch back to your Charon browser tab and look at Hecate → Agent. Your agent should show a green Online badge within 10–30 seconds.

Still showing "Pending"? That means the agent hasn't connected yet. Double-check:

  • The docker-compose.yml is saved correctly and docker compose up -d ran without errors
  • The auth key in the file matches what Charon gave you (no extra spaces or missing characters)
  • The remote machine has outbound internet access

Step 4 — (Optional) Assign a VPN Tunnel

Skip this step if your remote machine has a direct IP address that Charon can see — for example it's on the same local network, or it has a public IP. Go straight to Step 5.

If your remote machine is behind a NAT (no public IP) and you also use a VPN like NetBird or Tailscale, you can tell Hecate which VPN device is your remote machine. This lets Charon resolve the address automatically.

  1. First, add your VPN provider credentials: Settings → Tunnel Providers → Add Provider
  2. Then open your agent in Hecate → Agent
  3. Under Network Assignment, pick your provider and the device that represents the remote machine
  4. Click Save

Not sure which option applies to you? The Hecate guide explains each connection mode in plain English.


Step 5 — Add the Machine as a Source

  1. In the sidebar, open Hecate → Sources
  2. Click Add Source
  3. Give it a name and set Provider to Docker
  4. Set Connection Type to Orthrus Agent, then choose the agent you just registered
  5. Click Test Connection

If you see a green success message, Charon can reach your Docker. Click Save.

If the test fails, check that the agent still shows Online in Hecate → Agent. For a Source that you connect by host and port, see Diagnosing a Failed Connection Test below.


Step 6 — Use Your Containers

Your machine now appears in the Source dropdown anywhere Charon asks "which container?".

  1. Go to Proxy Hosts → Add Proxy Host
  2. Open the Source dropdown and select your machine (it shows the name you gave it)
  3. Browse the containers running there and pick one
  4. Fill in your domain name and click Save

Charon now proxies traffic through the Orthrus tunnel to reach that container. From the visitor's point of view, it's just a normal website with HTTPS.


Step 7 — (Optional) Let Another Tool Talk to Your Agent's Docker API

Skip this step unless you use a third-party tool — like an update-checker (Dockhand, Diun) or a monitoring dashboard — that wants to talk to your remote machine's Docker API directly.

  1. Go to Hecate → Agent
  2. Click the gear icon next to your agent
  3. Set a port (any number from 1024 to 65535) and click Save. Leave Listen on set to Automatic unless your tool runs on a different Docker network. In that case, choose the network your tool can reach.
  4. In your third-party tool, use the connection string tcp://<host>:<port> — Charon fills in <host> for you automatically, so just plug in the port you chose

Full detail: Orthrus guide → External Docker Proxy.


(Optional) Add Uptime Monitoring

Want to know immediately if a remote service goes down? Enable uptime monitoring on any proxy host that points to a remote container:

  1. Open the proxy host in Hosts
  2. Click Edit
  3. Scroll to Uptime Monitoring and toggle it on
  4. Click Save

Charon will check the service regularly and alert you through your configured notification channels if it becomes unreachable.

→ Learn more: Uptime Monitoring


Diagnosing a Failed Connection Test

Test Connection only tells you whether Charon could reach the machine. It shows Reachable in N ms on success, and Could not connect to the target. on failure. It does not say why, and Charon's logs do not record the address or port it tried. Only administrators can run this test.

If you connect a Source by its host and port and the test fails, check the address from inside the Charon container:

  1. On the machine that runs Charon, open a terminal.
  2. Run this command, replacing <host> and <port> with the address and port you entered in the Source:
docker exec charon nc -zv <host> <port>
  1. Read the answer:
What the command says What it means What to do
open or succeeded Charon can reach the address Save the Source. If Charon still says the test failed, try again in a minute
Connection refused The machine answers, but nothing listens on that port Check the port number and that Docker's remote API is turned on
timed out or No route to host The address is wrong, or a firewall blocks the way Check the address, and any firewall on the remote machine

If the command works but Charon still shows This destination is not allowed., the address is one Charon does not connect to, such as a link-local address or a port Charon uses for itself. See Which Addresses a Monitor Can Check for the list.

If you see Too many attempts, Charon allows 10 connection tests per minute for each account, shared by all connection tests. Wait a minute and try again.


Troubleshooting

Problem Likely Cause Fix
Agent stays Pending Install snippet not run yet Run docker compose up -d on the remote machine
Test Connection fails Agent is offline Check the agent container is running: docker ps
No containers listed Docker socket not mounted in agent Add -v /var/run/docker.sock:/var/run/docker.sock:ro to the agent's volumes
No containers listed, and the agent cannot open the socket PGID does not match the Docker group Set PGID to the output of stat -c '%g' /var/run/docker.sock, then run docker compose up -d again
Auth key rejected Key copied incorrectly Delete the agent, create a new one, copy the key carefully
Agent says the key is not set yet The orthrus_auth_key file is empty Paste your key into that file, then run docker compose up -d again
Agent says it cannot use the key file The file is missing, or the folder is not the one with docker-compose.yml Run the save command from Step 2 in the folder that holds docker-compose.yml, then run docker compose up -d again
Agent disconnects repeatedly Network instability Normal — the agent reconnects automatically, no action needed
Third-party tool can't reach my agent's Docker API Wrong port configured in the tool Check the tool is using the External Proxy port shown in the gear-icon dialog — not Charon's main web port

What's Next?

  • Orthrus guide — More detail on the agent, install methods, and the read-only safety filter
  • Hecate guide — All three connection modes explained, plus VPN provider setup