Hoody Proxy reference
Section titled “Hoody Proxy reference”Lookup tables for Hoody Proxy. Every route and field is in the API reference.
Service labels
Section titled “Service labels”The {service} part of https://{projectId}-{computerId}-{service}-{instance}.{server}.computers.hoody.com:
| Label | Reaches |
|---|---|
terminal, display, files, sqlite, exec, browser, agent, code, curl | The 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 |
n | Notifications (n-1) |
desktop | Starts or opens a desktop session |
cdp | The Chrome DevTools Protocol endpoint of the browser instance with the same number |
d-tcp | The direct display WebSocket endpoint |
daemon, cron, pipe, notes, watch, run, tunnel, egress, vm | The Kit service of that name |
logs | Proxy request logs |
http | Your own server; the instance is its port (http-3000) |
daemon, sqlite and pipe reach one service whatever the instance number.
Reserved ports
Section titled “Reserved ports”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.
| Port | Service | Port | Service |
|---|---|---|---|
4 | hoody-curl | 60 | hoody-cron |
5 | hoody-sqlite | 61 | hoody-watch |
44 | hoody-run | 62 | hoody-vm |
45 | hoody-agent | 75 | hoody-exec |
46 | hoody-notes | 76 | hoody-terminal |
48 | hoody-pipe | 77 | hoody-daemon |
50 | hoody-tunnel | 78 | hoody-files |
59 | hoody-egress |
Above 500, Hoody assigns pool ports as you start browser, display or code instances, so a port free now can be claimed later:
| Service | Fixed port | Dynamic pool |
|---|---|---|
hoody-code | 3971 | instances from 60000 |
hoody-display | 3998 | sessions from 4000 |
hoody-notifications | 3999 | None |
hoody-browser | 23333 | HTTP instances from 30000 |
hoody-browsernumbers its X displays from 501 (browser-1shows ondisplay-501). Those are display numbers, not TCP ports.- Port
22is not reserved: SSH to a computer needs nosshdinside it.
Bind addresses
Section titled “Bind addresses”| Your service listens on | Reachable through the proxy |
|---|---|
0.0.0.0 | Yes, always |
127.0.0.1 | Normally, 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 only | No |
Stop Kit services
Section titled “Stop Kit services”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.
HTTPS and certificates
Section titled “HTTPS and certificates”| Item | Behaviour |
|---|---|
| Certificate | Wildcard *.{server}.computers.hoody.com, issued and renewed by Hoody |
| TLS | 1.2 and later |
| Plain HTTP | Redirected to HTTPS |
| Certificate Transparency | Logs show only the wildcard, never your computer URLs |
| Custom domain | Let’s Encrypt certificate issued automatically once your DNS points at an alias |
| URL guessing | 24 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 |
Limits and caching
Section titled “Limits and caching”| Item | Behaviour |
|---|---|
| Request to a computer service | Capped at 10 GiB, before the Kit service’s own limit applies. Each Kit service’s limits are on its API page |
| Forward-proxy request body | Capped at 150 MiB |
| Caching | None: 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-Charset | Ignored and not passed to the client |
X-Accel-Buffering | Ignored and not passed to the client. Streams stay unbuffered whatever its value |
| Concurrent connections | Thousands of WebSocket connections per service, with HTTP keep-alive |
Error responses
Section titled “Error responses”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.
| Request | Format |
|---|---|
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 else | The Accept header picks application/json, text/html or text/plain, using q-values as in RFC 9110 |
A tie, or no Accept | Preference 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 acceptable | JSON |
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" }| Header | When |
|---|---|
X-Hoody-Error-Code | Same code, when it is upper case. permission_backend_unavailable and migration_pending appear only in the body |
Cache-Control: no-store | Always |
Vary: Accept, Sec-Fetch-Dest, User-Agent | Always, added to any Vary already present |
WWW-Authenticate | On a 401 that has one |
Retry-After | On 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.
| Status | Code when no specific one applies |
|---|---|
| 400 | BAD_REQUEST |
| 401 | AUTH_REQUIRED |
| 403 | ACCESS_DENIED |
| 404 | NOT_FOUND |
| 413 | REQUEST_BODY_TOO_LARGE |
| 421 | MISDIRECTED_REQUEST |
| 429 | RATE_LIMITED |
| 431 | REQUEST_HEADERS_TOO_LARGE (HTTP/1.1; over HTTP/2 the request gets no response) |
| 500 | INTERNAL_ERROR |
| 502 | BACKEND_GATEWAY_ERROR |
| 503 | SERVICE_UNAVAILABLE |
| 504 | BACKEND_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.
Computer permissions example
Section titled “Computer permissions example”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.
# 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>'await client.api.computers.proxy.setPermissions(COMPUTER_ID, { project: PROJECT_ID, computer: COMPUTER_ID, groups: { public: { type: 'ip', range: '0.0.0.0/0' } }, permissions: { public: { http: [8080], files: false } }, default: 'deny'}, { ifMatch: 'file:v<N>' });# The If-Match ETag (file:v<N>) comes from a prior GET of the permissions document.curl -X PUT "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/proxy/permissions" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -H "If-Match: file:v<N>" \ -d '{ "project": "'$PROJECT_ID'", "computer": "'$COMPUTER_ID'", "groups": { "public": { "type": "ip", "range": "0.0.0.0/0" } }, "permissions": { "public": { "http": [8080], "files": false } }, "default": "deny" }'Run this link through a separate computer in a different project whose cURL URL stays reachable. Replaces the computer-level document only. Fetch the current document first and put its ETag in place of file:v<N>.
https://WRAPPER_PROJECT_ID-WRAPPER_COMPUTER_ID-curl-1.WRAPPER_SERVER.computers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/computers/COMPUTER_ID/proxy/permissions&method=PUT&bearer_token=HOODY_TOKEN&header=If-Match:%20file:v<N>&json={"project":"PROJECT_ID","computer":"COMPUTER_ID","groups":{"public":{"type":"ip","range":"0.0.0.0/0"}},"permissions":{"public":{"http":[8080],"files":false}},"default":"deny"}&response=transparentOne request, one link
cURL runs inside your computer and can wrap any HTTP request into a single GET URL. The call stops being something you need a client for and becomes something you can paste into a browser, send in a chat, bookmark, schedule with cron, or drop into a no-code tool.
Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials. It also appears in the cURL service's request log, not only the target's. Prefer a delegated token with minimal permissions and an expiry: see API tokens.
Slashes, colons and braces pass through as they are. The one character you must
encode is an & inside a value, which happens when the wrapped URL
carries its own query string. Left raw it ends the value early, and the rest is
read as cURL's own parameters, so you get a 200 on a request you did
not make.
How the wrapping works Chaining calls into one link Turning a link into a shortcut
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.
Questions
Section titled “Questions”| Question | Answer |
|---|---|
| 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 |
API pages
Section titled “API pages”| Page | Covers |
|---|---|
| Proxy aliases | Custom subdomains |
| Proxy permissions | Project and computer access rules |
| Proxy settings | enable_proxy and default |
| Computer network | Proxy and VPN routing |
| Computer firewall | Network-level rules |
| Computer operations | Start and stop computers |
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | What to do |
|---|---|---|
| Service URL gives connection errors or timeouts | The computer is not running, or the service is not started | Check 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 work | No such service: the shell is terminal | Use a label from runtime_info or Service labels |
| 401 or 403 on a computer or alias URL | Proxy permissions are set and you match no group, or a group you match denies the requested program | Read 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 it | The proxy is disabled. It looks like any denial: Error 403: Access denied. for CLI clients, the standard error page in a browser | Read 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 warning | Should not happen: every *.{server}.computers.hoody.com URL has a valid certificate | Clear the browser cache, try another browser, check the system clock, and check the hostname for typos |
http-3000 connection error | Nothing listens on that port, the port in the URL is wrong, or the bind address | Check 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’s | The request went through a proxy hook, or the app reads the wrong field | A 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) |