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¶
- In the Charon sidebar, open Hecate → Agent (admins only)
- Click Add Agent
- Type a name for this machine — something like "HomeLab" or "NAS Box"
- 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.
Using Docker Compose (recommended)¶
On your remote machine, open a terminal and:
- Create a new folder for the agent:
mkdir orthrus-agent && cd orthrus-agent - Copy the Docker Compose snippet from the Charon UI
- Create a file called
docker-compose.ymland paste the snippet into it - 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 namedorthrus_auth_key. Your key stays in that file and is not written intodocker-compose.yml. See Keep the Auth Key in a File. - Check the permission settings. The file should include
PUID,PGID, andTZlines. SetPGIDto your Docker group's number: runstat -c '%g' /var/run/docker.sockon the remote machine and put the number it prints afterPGID=. Most setups need this. See Set the Permissions for details.
Heads up: That number goes in
PGIDonly.DOCKER_SOCKstays the socket's path (/var/run/docker.sock); do not build it from the number. To check it, rungetent group <number>; it should print thedockergroup.Using rootless Docker? The settings are different. See Rootless Docker. 6. Run:
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.ymlis saved correctly anddocker compose up -dran 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.
- First, add your VPN provider credentials: Settings → Tunnel Providers → Add Provider
- Then open your agent in Hecate → Agent
- Under Network Assignment, pick your provider and the device that represents the remote machine
- 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¶
- In the sidebar, open Hecate → Sources
- Click Add Source
- Give it a name and set Provider to Docker
- Set Connection Type to Orthrus Agent, then choose the agent you just registered
- 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?".
- Go to Proxy Hosts → Add Proxy Host
- Open the Source dropdown and select your machine (it shows the name you gave it)
- Browse the containers running there and pick one
- 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.
- Go to Hecate → Agent
- Click the gear icon next to your agent
- 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.
- 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:
- Open the proxy host in Hosts
- Click Edit
- Scroll to Uptime Monitoring and toggle it on
- 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:
- On the machine that runs Charon, open a terminal.
- Run this command, replacing
<host>and<port>with the address and port you entered in the Source:
- 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