Agent

The agent is one long-running process per machine that serves every endpoint you declare in the dashboard. Add, edit, or remove an endpoint at hle.world/dashboard and the agent converges within seconds — no restart, no SSH, no process per tunnel.

	hle expose	hle agent
Tunnels per process	one	many
Configured in	the command line	the dashboard
Changing a tunnel	restart the command	takes effect in seconds
Credential	API key (hle_…)	agent token (hlea_…)

Use hle expose for a quick one-off share. Use the agent for anything you want to keep running.

An endpoint’s target is any URL the agent can reach — not just services on its own machine, but anything on its network.

What an agent also unlocks

Firepuncher	Reach any TCP port the agent can see — SSH, Postgres, RDP — with no port open anywhere
Service discovery	The agent inventories your Kubernetes Services and Docker containers so you can expose one in a click
Traffic & metrics	One chart and one metric strip for the agent, each endpoint, and every forward

Note

Agents are available on every account — there is nothing to switch on. If you would rather run a single tunnel from the command line, hle expose is unchanged and is not going away.

Install

The installer sets up the client, enrolls the machine, and installs a service that starts at boot — in one command:

curl -fsSL https://get.hle.world | sh -s -- --agent

It prompts for the agent token. To get one, go to Connections → New → Agent in the dashboard and copy the hlea_… value. It is shown only once.

For unattended installs (cloud-init, Ansible, CI), pass the token instead:

curl -fsSL https://get.hle.world | sh -s -- --agent --token hlea_xxxxx

Installer options

Flag	Effect
--agent	Enroll the machine and install the agent service
--token <hlea_…>	Provide the token non-interactively (implies --agent)
--no-service	Enroll only — don’t install a service
--user	Per-user service (no sudo)
--system	System-wide service, starts at boot (needs sudo)
--version <v>	Pin a specific hle-client version

Without --user or --system the scope is auto-detected: running as root installs a system service, otherwise a per-user one.

Manual setup

If you already have the client installed:

hle agent enroll              # prompts for the token
hle service install --agent   # install + start the background service

Or run it in the foreground to watch what it does:

hle agent run

Add endpoints

Everything else happens in the dashboard, under Connections → Agents → your agent → Endpoints. Each endpoint has:

• Label — used in the public hostname (e.g. ha → ha-x7k.hle.world)
• Local URL — where the agent should forward to (e.g. http://localhost:8123)
• Domain — the base domain, or one of your custom zones
• Auth — SSO or open

A typical homelab agent:

Label	Local URL	Public URL	Auth
ha	http://homeassistant:8123	ha-x7k.hle.world	SSO
jelly	http://nas:8096	jelly.example.com	SSO
git	http://git:3000	git-x7k.hle.world	SSO

Manage the service

hle service status --agent      # is it running?
hle service uninstall --agent   # stop, disable, and remove it

Under the hood this is a systemd unit (hle-agent.service) on Linux and a launchd job (world.hle.agent) on macOS. Read the logs with:

# Linux, system service
sudo journalctl -u hle-agent -f

# Linux, per-user service
journalctl --user -u hle-agent -f

# macOS
tail -f ~/Library/Logs/hle/agent.log

Per-user services and logout

A per-user systemd service stops when you log out unless lingering is enabled:

sudo loginctl enable-linger $USER

A system service (--system) has no such caveat — prefer it on a headless box.

Where the token lives

hle agent enroll writes the token to ~/.config/hle/agent.toml with mode 0600. It is never written into the service definition, so the unit file is safe to read, back up, or commit as a template.

A system service runs as a specific user (--run-as, defaulting to whoever ran the install) and reads that user’s agent.toml. If you enroll as one user and install the service as another, the agent won’t find the token — enroll as the same user, or set HLE_AGENT_TOKEN in the unit’s environment.

You can also supply the token entirely by environment variable, which is what the container images do:

export HLE_AGENT_TOKEN=hlea_xxxxx
hle agent run

Rotating or removing a token

Tokens can’t be retrieved after creation. To rotate one, create a new agent in the dashboard, re-enroll, and restart the service:

hle agent enroll                    # paste the new token
hle service uninstall --agent
hle service install --agent

To remove the saved token from a machine:

hle agent logout

Containers and platforms

• Docker — HLE_AGENT_TOKEN with the agent profile
• Home Assistant — the agent_token add-on option
• Proxmox — one agent per node or LXC
• Unraid — agent container template

Troubleshooting

The agent shows offline in the dashboard. Check the service is running (hle service status --agent) and look at the logs. The agent needs outbound HTTPS to hle.world:443; it never accepts inbound connections.

An endpoint shows an error. The agent could reach the server but not your local service. Verify the local URL from the machine running the agent — inside a container, localhost is the container, not the host.

“No agent token” on service start. The service is running as a user without ~/.config/hle/agent.toml. See Where the token lives.