HF PanelDocsv1.0.0

Desktop app API

The free HF Tunnel links the HF Server desktop app makes with a device key, under /v1/desktop, with no account or token.

The HF Server desktop app can share a website running on your computer through a server's HF Tunnel, even without a hosting account there. It uses the /v1/desktop/… addresses for that. They need no API token: each computer identifies itself with its own device key, and its links belong to that key alone.

Note: you normally never call these addresses yourself; the desktop app does. This page is for administrators who want to know what the app does on their server.

The device key

The app makes a random key once and sends it on every request:

http
X-HF-Device: 4f1c…   (64 lower-case hexadecimal characters)

HF Panel stores only a hash of the key. A missing or malformed key answers 401 "Send the computer key: X-HF-Device: <64 hex characters>." At most 5 new computers can register from one IP address in 24 hours (429).

Endpoints

The base address is the same as the token API: https://api.yourdomain.com:2087/v1 (old address: https://panel.yourdomain.com:8443/api/v1).

Method Path Body Answer data
GET /v1/desktop/endpoint enabled, domain, server_addr, server_port, limit
GET /v1/desktop/tunnels enabled, domain, limit, server_online, server_addr, server_port, tunnels[]
POST /v1/desktop/tunnels {"name","port"} (port default 80) 201, the new link
GET /v1/desktop/tunnels/{name}/client what the tunnel client needs: name, url, server_addr, server_port, auth_token, user, key, arches[], and tls_ca, tls_server_name when it connects to this server
DELETE /v1/desktop/tunnels/{name} {"deleted": "<name>"}

Each link has the same fields as a tunnel: name, url, port, online, created_at.

bash
curl -s https://api.yourdomain.com:2087/v1/desktop/tunnels \
     -H "X-HF-Device: $(cat ~/.hf-device-key)" \
     -H 'Content-Type: application/json' -d '{"name":"myapp","port":3000}'
Status When
404 no such link on this computer, or the computer has no links yet
409 the name is taken: "myapp.port.yourdomain.com is taken — pick another name."
422 a bad name (1–32 lower-case letters, numbers and -, not at the start or end), or the computer already has its maximum number of links
503 free links are switched off, all free links are in use, or the tunnel server is not ready

Limits and settings

Rule Default
Links per computer 3 (the administrator can set 1–20)
Free links on the server in all 200 (0 = no limit)
Unused links are removed after 60 days without use; computers with no links left are forgotten too

Free links work only when HF Tunnel is set up and the administrator has not switched desktop links off. While they are off, GET /v1/desktop/tunnels answers "enabled": false with an empty list, and every other address answers 503 "Free HF Tunnel links are switched off on this server."