Skip to content

Beta: these docs are still being updated. The next full update is on 19 November at 8 PM UTC. Docs in beta. Full update 19 Nov, 8 PM UTC.

Hoody.com

Lookup tables for Hoody Proxy. Every route and field is in the API reference.

The {service} part of https://{projectId}-{computerId}-{service}-{instance}.{server}.computers.hoody.com:

LabelReaches
terminal, display, files, sqlite, exec, browser, agent, code, curlThe Kit service of that name, except agent: /api/v1/agent and its subpaths reach Hoody Agent; other paths open the agent’s TUI through Hoody Terminal
nNotifications (n-1)
desktopStarts or opens a desktop session
cdpThe Chrome DevTools Protocol endpoint of the browser instance with the same number
d-tcpThe direct display WebSocket endpoint
daemon, cron, pipe, notes, watch, run, tunnel, egress, vmThe Kit service of that name
logsProxy request logs
httpYour own server; the instance is its port (http-3000)

daemon, sqlite and pipe reach one service whatever the instance number.

With Hoody Kit on, its HTTP services listen on 0.0.0.0 at these ports inside each computer’s own network. They are not public ports and are never shared between computers. Ports 80 to 499 are always clear of the Kit.

PortServicePortService
4hoody-curl60hoody-cron
5hoody-sqlite61hoody-watch
44hoody-run62hoody-vm
45hoody-agent75hoody-exec
46hoody-notes76hoody-terminal
48hoody-pipe77hoody-daemon
50hoody-tunnel78hoody-files
59hoody-egress

Above 500, Hoody assigns pool ports as you start browser, display or code instances, so a port free now can be claimed later:

ServiceFixed portDynamic pool
hoody-code3971instances from 60000
hoody-display3998sessions from 4000
hoody-notifications3999None
hoody-browser23333HTTP instances from 30000
  • hoody-browser numbers its X displays from 501 (browser-1 shows on display-501). Those are display numbers, not TCP ports.
  • Port 22 is not reserved: SSH to a computer needs no sshd inside it.
Your service listens onReachable through the proxy
0.0.0.0Yes, always
127.0.0.1Normally, because hoody-daemon forwards the computer’s incoming IPv4 traffic to loopback. That forwarding can be turned off, and a computer where it could not be set up lacks it, so bind to 0.0.0.0 when the service must be reachable
::1 onlyNo

In the Hub, open Programs, select the computer in the top bar, open Running programs, expand System programs, and choose the Stop entry named after the service (for example Stop hoody-agent) from the service’s row menu, or select the service and press Stop in its details. Review the warning and confirm Stop it. To disable a service, use Daemons. Stopping alone can let Hoody Proxy start it again on the next request. The daemon itself runs as the systemd unit hoody-daemon.service, which restarts it if its process ends, so stop it with systemctl over SSH.

ItemBehaviour
CertificateWildcard *.{server}.computers.hoody.com, issued and renewed by Hoody
TLS1.2 and later
Plain HTTPRedirected to HTTPS
Certificate TransparencyLogs show only the wildcard, never your computer URLs
Custom domainLet’s Encrypt certificate issued automatically once your DNS points at an alias
URL guessing24 hex characters per ID is 2^96 combinations; at a billion guesses a second, trillions of years. The URL is still a bearer credential: anyone it leaks to (browser history, chat or CI logs, referer headers, screenshots) can use it
ItemBehaviour
Request to a computer serviceCapped at 10 GiB, before the Kit service’s own limit applies. Each Kit service’s limits are on its API page
Forward-proxy request bodyCapped at 150 MiB
CachingNone: request and response bodies stream straight through. Your Cache-Control headers reach the client unchanged
X-Accel-Redirect, X-Accel-Expires, X-Accel-Limit-Rate, X-Accel-CharsetIgnored and not passed to the client
X-Accel-BufferingIgnored and not passed to the client. Streams stay unbuffered whatever its value
Concurrent connectionsThousands of WebSocket connections per service, with HTTP keep-alive

These apply when the proxy itself refuses a request: a permission denial, a computer still provisioning, a body over the limit, a rate limit, or a computer that does not answer. A Kit service answers with its own codes, and your app’s errors pass through unchanged.

RequestFormat
Page load (Sec-Fetch-Dest: document, iframe or frame)The HTML error page
fetch() or XHR (Sec-Fetch-Dest: empty, script and similar)Never the HTML page
Anything elseThe Accept header picks application/json, text/html or text/plain, using q-values as in RFC 9110
A tie, or no AcceptPreference among the tied types only: curl gets plain text, then HTML, then JSON; every other client JSON, then HTML, then plain text. So a non-curl client accepting only text/* gets HTML, and curl with Accept: application/json, text/html gets HTML
None of the three acceptableJSON

The JSON body has a fixed message and a code. A plain-text 403 is Error 403: Access denied.; a 503 with Retry-After adds Retry-After: <seconds> seconds on a second line. For example, a JSON 403 is:

{ "error": "Access denied.", "errorCode": "ACCESS_DENIED" }
HeaderWhen
X-Hoody-Error-CodeSame code, when it is upper case. permission_backend_unavailable and migration_pending appear only in the body
Cache-Control: no-storeAlways
Vary: Accept, Sec-Fetch-Dest, User-AgentAlways, added to any Vary already present
WWW-AuthenticateOn a 401 that has one
Retry-AfterOn a 503 that has one

A cross-origin page can read a proxy error when the response permits its origin, as permission refusals do; when X-Hoody-Error-Code is present, it is then in Access-Control-Expose-Headers. That includes the proxy’s own 502, 503 and 504 responses to an admitted request, under the default CORS policy or a matching allowlist grant. Errors without a CORS grant stay unreadable to it.

StatusCode when no specific one applies
400BAD_REQUEST
401AUTH_REQUIRED
403ACCESS_DENIED
404NOT_FOUND
413REQUEST_BODY_TOO_LARGE
421MISDIRECTED_REQUEST
429RATE_LIMITED
431REQUEST_HEADERS_TOO_LARGE (HTTP/1.1; over HTTP/2 the request gets no response)
500INTERNAL_ERROR
502BACKEND_GATEWAY_ERROR
503SERVICE_UNAVAILABLE
504BACKEND_TIMEOUT

No formatted error: a request the proxy cannot parse (a malformed request line, a URL over the length limit) or a method it does not accept, such as TRACE, gets the server’s plain default page. TLS failures, HTTP/2 protocol errors and failures inside an open tunnel close the connection with no HTTP response.

This replaces one computer’s document so that HTTP port 8080 is open to everyone and files are refused, except to callers a project group allows files. The project document stays in force except where entries overlap; the computer wins overlaps.

The replacement also replaces the computer’s hooks and its own enable_proxy, so a hook that gates access is gone, and a computer switched off follows the project again, unless the body carries them. Copy hooks from a GET into the body, or use the granular commands at the end of the CLI tab, which leave hooks alone.

Terminal window
# Read file_version first with `hoody computers proxy permissions get -c "$COMPUTER_ID" -o json`
hoody computers proxy permissions set -c "$COMPUTER_ID" --project $PROJECT_ID --if-match 'file:v<N>' \
--groups public='{"type": "ip", "range": "0.0.0.0/0"}' \
--permissions public='{"http": [8080], "files": false}' \
--default deny
# `permissions set` replaces the whole document (one NAME='<json>' per group, or the
# whole object inline, as @file.json or @-). The commands below set only the fields they
# name, so groups and permissions already in the document stay and earlier access can
# survive; they match the one-call form only from an empty document. To remove an entry use
# `hoody computers proxy groups delete <name> -c "$COMPUTER_ID"` or
# `hoody computers proxy groups permissions delete <name> <program> -c "$COMPUTER_ID"`,
# each with --if-match. Re-read file_version before every command.
hoody computers proxy groups ip set public -c "$COMPUTER_ID" \
--range 0.0.0.0/0 --if-match 'file:v<N>'
hoody computers proxy groups permissions set public http -c "$COMPUTER_ID" \
--access '[8080]' --if-match 'file:v<N>'
hoody computers proxy groups permissions set public files -c "$COMPUTER_ID" \
--access false --if-match 'file:v<N>'
hoody computers proxy default set -c "$COMPUTER_ID" --default deny --if-match 'file:v<N>'

The project form is the same with hoody projects proxy ... and --project $PROJECT_ID, for example hoody projects proxy groups delete <name> --project $PROJECT_ID.

QuestionAnswer
Can I run my own reverse proxy in a computer?Yes: nginx, Caddy, Traefik or any other. Hoody Proxy routes to its port, for example http-80, and it routes on to your backends
Does the proxy add latency?<1ms for TLS termination and client-IP handling; your app’s own response time dominates
Why does api.hoody.com not follow the pattern?The Hoody API manages the platform (create computers, configure networks, manage billing) and carries no project or computer prefix. Computer URLs reach the services inside a computer
Do computers on different servers talk through the proxy?Yes, through their public URLs. Realms isolate API access (token scoping), not networking
PageCovers
Proxy aliasesCustom subdomains
Proxy permissionsProject and computer access rules
Proxy settingsenable_proxy and default
Computer networkProxy and VPN routing
Computer firewallNetwork-level rules
Computer operationsStart and stop computers
SymptomCauseWhat to do
Service URL gives connection errors or timeoutsThe computer is not running, or the service is not startedCheck that GET /api/v1/computers/{computer_id}?runtime=true shows status: "running"; if not, start the computer with POST /api/v1/computers/{computer_id}/{operation} and operation start. When runtime_info is present, look for the service there; if it is missing, check the service over SSH or a terminal URL
A URL with the service label shell-1 does not workNo such service: the shell is terminalUse a label from runtime_info or Service labels
401 or 403 on a computer or alias URLProxy permissions are set and you match no group, or a group you match denies the requested programRead GET /api/v1/projects/{project_id}/proxy/permissions and GET /api/v1/computers/{computer_id}/proxy/permissions. For an IP group, check your address (curl https://ifconfig.me); for JWT or password, your credentials. To test without the computer’s document, save its GET body, then send DELETE /api/v1/computers/{computer_id}/proxy/permissions with If-Match: file:v<N> from that GET: the project document applies, or the computer is open if the project has none. The delete also removes the computer’s hooks and its own enable_proxy and default. To restore them, PUT the saved data without schema_version, file_version and etag, with If-Match from a fresh GET
Every URL answers 403 and no rule explains itThe proxy is disabled. It looks like any denial: Error 403: Access denied. for CLI clients, the standard error page in a browserRead enable_proxy in the project and the computer permissions, then send {"enable_proxy": true} to PATCH /api/v1/projects/{project_id}/proxy/permissions/state or PATCH /api/v1/computers/{computer_id}/proxy/permissions/state, with the If-Match value from a GET
Browser certificate warningShould not happen: every *.{server}.computers.hoody.com URL has a valid certificateClear the browser cache, try another browser, check the system clock, and check the hostname for typos
http-3000 connection errorNothing listens on that port, the port in the URL is wrong, or the bind addressCheck with netstat -tlnp | grep 3000 in the computer; use the app’s port in the URL; see Bind addresses
App sees a proxy address, not the client’sThe request went through a proxy hook, or the app reads the wrong fieldA hook that forwards the request shows its own connection address. Where you trust both Hoody Proxy and the hook, read the original client address from X-Real-IP; do not trust that header on direct traffic. For directly routed requests, read the connection address (req.socket.remoteAddress in Node.js)