Skip to content

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.

  1. Go to Hecate → Agent and open the agent
  2. Under Network Assignment, pick your Provider and the Device that represents your remote machine
  3. 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.