hle-tunnel（隧道）

HLE Tunnel

Access your agent's web UI from anywhere and share it with others — secure remote access with automatic HTTPS and SSO, powered by HLE (Home Lab Everywhere).

When to use

Use this skill when the user wants to:

• Access their agent's Control UI (port 18789) remotely — from a phone, laptop, or another network
• Share their agent UI with a friend or collaborator via SSO (Google, GitHub)
• Expose any local service the agent manages — Home Assistant, Grafana, Portainer, Jupyter, dev servers
• Manage tunnel access control (SSO, PIN, share links, basic auth)

Do not use this skill for general networking, port forwarding within a LAN, or VPN setup.

Setup

Before exposing services, the user needs an HLE account and API key:

1. Sign up at https://hle.world and create an API key in the dashboard
2. Run hle auth login to save the key (opens browser), or set the HLE_API_KEY environment variable

Check auth status with hle auth status.

Usage

Access your agent UI remotely

# Expose the Control UI so you can access it from anywhere
hle expose --service http://localhost:18789 --label my-agent

# Share access with a collaborator via SSO
hle expose --service http://localhost:18789 --label my-agent \
  --allow friend@gmail.com

# Allow multiple people
hle expose --service http://localhost:18789 --label my-agent \
  --allow teammate1@company.com --allow teammate2@company.com

The command runs in the foreground and prints the public URL (e.g. https://my-agent-x7k.hle.world). Anyone you --allow can log in via Google or GitHub SSO — no account sharing needed.

Expose services your agent manages

# Home Assistant
hle expose --service http://localhost:8123 --label ha \
  --allow you@gmail.com

# Grafana dashboard — share with your team
hle expose --service http://localhost:3000 --label grafana \
  --allow dev1@company.com --allow dev2@company.com

# Dev server — share with a client for a demo
hle expose --service http://localhost:3000 --label dev \
  --allow client@company.com

# Jupyter notebook — share with a colleague
hle expose --service http://localhost:8888 --label notebook \
  --allow colleague@company.com

List active tunnels

hle tunnels

Access control

# Allow a specific email to access a tunnel via SSO
hle access add my-agent-x7k friend@example.com

# Set a PIN for quick access
hle pin set my-agent-x7k

# Create a temporary share link (expires in 24h by default)
hle share create my-agent-x7k --duration 1h --max-uses 5

# Set HTTP Basic Auth
hle basic-auth set my-agent-x7k

Common options for hle expose

Run with Docker

If Docker is available, you can run HLE as a container instead of installing the CLI.

Headless (tunnels only, no UI)

docker run -d \
  --name hle \
  -e HLE_API_KEY=your_key_here \
  -v hle-data:/data \
  ghcr.io/hle-world/hle-docker:headless

# Expose your agent's Control UI running on the Docker host
docker exec hle hle expose \
  --service http://host.docker.internal:18789 \
  --label my-agent \
  --allow you@gmail.com

With Web UI

docker run -d \
  --name hle \
  -p 8099:8099 \
  -e HLE_API_KEY=your_key_here \
  -v hle-data:/data \
  ghcr.io/hle-world/hle-docker:latest

Open http://localhost:8099 to manage tunnels from a browser.

Docker Compose

services:
  hle:
    image: ghcr.io/hle-world/hle-docker:headless
    restart: unless-stopped
    volumes:
      - hle-data:/data
    environment:
      - HLE_API_KEY=your_key_here

volumes:
  hle-data:

Important notes

• The hle expose command runs in the foreground. To run as a background service, use nohup, tmux, screen, or a process manager.
• Self-signed certificates on local services are accepted by default (no --verify-ssl needed).
• The public URL format is https://<label>-<user_code>.hle.world.
• By default, only you (the account owner) can access the tunnel. Use --allow to grant access to others via SSO.
• API key can be set via --api-key flag, HLE_API_KEY env var, or ~/.config/hle/config.toml.

Installation

If hle is not installed:

# Homebrew (macOS/Linux)
brew install hle-world/tap/hle-client

# pip/pipx
pipx install hle-client
# or: pip install hle-client