Hecate — Tunnel & Pathway Manager¶
Think of Hecate as a traffic controller standing at a crossroads. When Charon needs to reach a Source (a machine running your containers), Hecate decides which road to take: type in the address directly, send a message through the Orthrus agent you installed, or route through your VPN.
You interact with Hecate every time you add a Source — it's the part that asks "how do you want to connect?"
When Do You Need Hecate?¶
Direct Mode users: You don't need to configure Hecate at all. Just type in the IP address or hostname and you're done.
Agent Mode users (Orthrus): Register an Orthrus agent first (see the Orthrus guide). Hecate then fills in the connection address automatically — no IP address hunting required.
Provider Mode users: Your server is already on a VPN (like NetBird or Tailscale). Go to Settings → Tunnel Providers, add your VPN credentials there first, then Hecate can find your device on that network.
The Three Connection Modes¶
When you add a Source, you choose one of these modes:
| Mode | When To Use | What You Provide |
|---|---|---|
| Direct | The machine is on your local network or has a public IP | Hostname or IP address + port |
| Agent | You installed Orthrus on the remote machine | Just pick the agent from the list |
| Provider | The machine is already on a VPN, no agent needed | Pick the VPN provider + the device |
Direct Mode¶
You know where the server is — type in its address. This is the simplest option. Use it for machines on your home network or servers with a static public IP.
Agent Mode¶
You installed the Orthrus agent on the remote machine. Select it from the dropdown, and Charon fills in the connection details automatically from the agent's network information. You never have to know the IP address.
Provider Mode¶
Your remote machine is already connected to a VPN service like NetBird, Tailscale, Cloudflare Tunnel, or ZeroTier. Add your VPN credentials once in Settings → Tunnel Providers, then pick that provider and the specific device when configuring the Source. No agent installation needed.
Viewing Your Agents¶
Open Hecate → Agent in the sidebar (admins only) to see all your Orthrus agents at a glance. Each one shows a live status badge:
| Badge | Meaning |
|---|---|
| 🟢 Green | Connected and healthy |
| 🟡 Yellow | Connecting or experiencing delays |
| 🔴 Red | Unreachable |
Click any agent to see its details, change its name, view install instructions, or assign it to a tunnel provider.
Supported Tunnel Providers¶
These VPN and tunnel services work with Provider Mode:
| Provider | What You Need |
|---|---|
| NetBird | NetBird API key |
| Tailscale | Tailscale API key |
| Cloudflare | Cloudflare Tunnel credentials |
| ZeroTier | ZeroTier network ID + node details |
Self-hosted NetBird or ZeroTier controllers: your controller must be reachable at a public https address. Controllers that can only be reached through a private or VPN-style address (including Tailscale-style 100.64.x.x) are refused. The default hosted services are not affected.
ZeroTier network IDs must be exactly 16 lowercase letters and digits (0-9, a-f). Anything else is rejected with an "invalid network id" message.
To add a provider: Settings → Tunnel Providers → Add Provider → choose your type → enter credentials → save.
Assigning a Tunnel to an Orthrus Agent¶
If your agent is on a VPN, you can tell Charon exactly where on that network it lives. After you do this, Charon remembers the address — so the next time you add a Source using this agent, everything fills in automatically.
- Go to Hecate → Agent and open the agent
- Under Network Assignment, pick your Provider and the Device that represents your remote machine
- Click Save
Uptime Monitoring Integration¶
Sources managed through Orthrus agents work with Uptime Monitoring. Enable monitoring on any proxy host that routes to a remote container, and Charon will alert you if that service goes down — even if it's on a machine behind a firewall on the other side of the world.
Troubleshooting¶
| Problem | Likely Cause | Fix |
|---|---|---|
| Provider shows an error state | Bad credentials or expired API key | Re-enter credentials in Settings → Tunnel Providers |
| Agent Mode address not filling in | No network assignment set on the agent | Open the agent → assign a Provider + Device → save |
| Tunnel keeps restarting | VPN provider is temporarily unreachable | This is normal — Hecate retries automatically with increasing delays |
| Device not listed in Provider Mode | Provider not yet configured | Add the provider in Settings first |
| Self-hosted NetBird/ZeroTier controller refused | Controller is only reachable on a private or VPN address | Make it reachable at a public https address |
| "invalid network id" | ZeroTier network ID is not 16 lowercase letters/digits | Copy the ID again from your ZeroTier dashboard |
Need to set up an Orthrus agent first? See the Orthrus guide. Ready to connect a remote Docker host? Follow the Remote Docker Setup Guide.