Skill: jspanos/hle-tunnel (version 1.2.0)

--- name: hle-tunnel description: Access your AI agent's web UI from anywhere and share it securely — automatic HTTPS, SSO access control, no VPN or port forwarding needed. version: 1.2.0 emoji: "\U0001F310" homepage: https://hle.world/docs/integrations/openclaw user-invocable: true skillKey: hle metadata: openclaw: requires: anyBins: - hle - pipx - pip env: - HLE_API_KEY install: - kind: brew formula: hle-world/tap/hle-client bins: [hle] - kind: uv package: hle-client bins: [hle] --- # 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)](https://hle.world). ## 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 ```bash # 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 [REDACTED_SECRET] # Allow multiple people hle expose --service http://localhost:18789 --label my-agent \ --allow [REDACTED_SECRET] --allow [REDACTED_SECRET] ``` 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 ```bash # Home Assistant hle expose --service http://localhost:8123 --label ha \ --allow [REDACTED_SECRET] # Grafana dashboard — share with your team hle expose --service http://localhost:3000 --label grafana \ --allow [REDACTED_SECRET] --allow [REDACTED_SECRET] # Dev server — share with a client for a demo hle expose --service http://localhost:3000 --label dev \ --allow [REDACTED_SECRET] # Jupyter notebook — share with a colleague hle expose --service http://localhost:8888 --label notebook \ --allow [REDACTED_SECRET] ``` ### List active tunnels ```bash hle tunnels ``` ### Access control ```bash # Allow a specific email to access a tunnel via SSO hle access add my-agent-x7k [REDACTED_SECRET] # 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` | Flag | Description | |------|-------------| | `--service URL` | Local service URL (required) | | `--label NAME` | Subdomain label (e.g. `my-agent` -> `my-agent-x7k.hle.world`) | | `--auth sso\|none` | Auth mode (default: `sso`) | | `--allow EMAIL` | Allow email for SSO access (repeatable) | | `--websocket/--no-websocket` | WebSocket proxying (default: on) | | `--verify-ssl` | Verify local service SSL cert | | `--upstream-basic-auth USER:PASS` | Inject Basic Auth to upstream | | `--forward-host` | Forward browser Host header to local service | ## Run with Docker If Docker is available, you can run HLE as a container instead of installing the CLI. ### Headless (tunnels only, no UI) ```bash 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 [REDACTED_SECRET] ``` ### With Web UI ```bash 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 ```yaml 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: ```bash # Homebrew (macOS/Linux) brew install hle-world/tap/hle-client # pip/pipx pipx install hle-client # or: pip install hle-client ```

path: references/examples.md
content: # HLE Tunnel Examples

## Agent UI — remote access

```bash
# Access your agent's Control UI from anywhere
hle expose --service http://localhost:18789 --label my-agent

# Share with a collaborator via SSO
hle expose --service http://localhost:18789 --label my-agent \
  --allow [REDACTED_SECRET]

# Allow multiple users
hle expose --service http://localhost:18789 --label my-agent \
  --allow [REDACTED_SECRET] --allow [REDACTED_SECRET]
```

## Homelab services

```bash
# Home Assistant — allow yourself remotely
hle expose --service http://localhost:8123 --label ha \
  --allow [REDACTED_SECRET]

# Grafana — share dashboard with your team
hle expose --service http://localhost:3000 --label grafana \
  --allow [REDACTED_SECRET] --allow [REDACTED_SECRET]

# Jellyfin media server — share with family
hle expose --service http://localhost:8096 --label media \
  --allow [REDACTED_SECRET]

# Node-RED
hle expose --service http://localhost:1880 --label nodered \
  --allow [REDACTED_SECRET]

# Pi-hole admin
hle expose --service http://localhost:80 --label pihole \
  --allow [REDACTED_SECRET]

# Portainer
hle expose --service https://localhost:9443 --label portainer \
  --allow [REDACTED_SECRET]
```

## Development

```bash
# Next.js / React dev server — share with a client
hle expose --service http://localhost:3000 --label dev \
  --allow [REDACTED_SECRET]

# API server — share with a teammate
hle expose --service http://localhost:8000 --label api \
  --allow [REDACTED_SECRET]

# Jupyter notebook — share with a colleague
hle expose --service http://localhost:8888 --label notebook \
  --allow [REDACTED_SECRET]

# MCP server — share with a teammate
hle expose --service http://localhost:8080 --label mcp-server \
  --allow [REDACTED_SECRET]
```

## Docker

```bash
# Run HLE container (headless, no UI)
docker run -d --name hle -e HLE_API_KEY=your_key \
  -v hle-data:/data ghcr.io/hle-world/hle-docker:headless

# Expose the agent's Control UI running on the Docker host
docker exec hle hle expose \
  --service http://host.docker.internal:18789 \
  --label my-agent \
  --allow [REDACTED_SECRET]

# Expose a service running in another container (use container name or Docker network IP)
docker exec hle hle expose \
  --service http://my-other-container:8080 \
  --label backend \
  --allow [REDACTED_SECRET]
```

## Background tunnel with process manager

```bash
# Using nohup
nohup hle expose --service http://localhost:18789 --label my-agent > /dev/null 2>&1 &

# Using systemd (create a service file)
# /etc/systemd/system/hle-tunnel.service
# [Unit]
# Description=HLE Tunnel
# After=network.target
# [Service]
# ExecStart=hle expose --service http://localhost:18789 --label my-agent
# Restart=always
# Environment=HLE_API_KEY=hle_your_key_here
# [Install]
# WantedBy=multi-user.target
```

## Access control examples

```bash
# Grant SSO access to a user (they log in via Google/GitHub)
hle access add my-agent-x7k [REDACTED_SECRET]

# Create a share link that expires in 2 hours, max 3 uses
hle share create my-agent-x7k --duration 2h --max-uses 3 --label "client demo"

# Set a PIN for quick mobile access
hle pin set my-agent-x7k
# Enter: 1234

# List all access rules
hle access list my-agent-x7k

# Revoke a share link
hle share revoke my-agent-x7k 42
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector:  ()