Hecate — Tunnel & Pathway Manager
Think of Hecate as a traffic controller standing at a crossroads. When Charon needs to reach a remote server, 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 Remote Server — 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 Remote Server, 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 Remote Server. No agent installation needed.
Viewing Your Agents
Go to Remote Agents in the sidebar 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 |
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 Remote Server using this agent, everything fills in automatically.
- Go to Remote Agents and open the agent
- Under Network Assignment, pick your Provider and the Device that represents your remote machine
- Click Save
Uptime Monitoring Integration
Remote servers 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 |
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.