# Hoody Proxy reference **Page:** foundation/proxy/reference [Download Raw Markdown](./foundation/proxy/reference.md) --- # Hoody Proxy reference Lookup tables for [Hoody Proxy](/foundation/proxy/). Every route and field is in the [API reference](/api/proxy-permissions/). ## 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 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-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. ## 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 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](/kit/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. Disable a service to keep its URL unavailable; stopping it or ending its process alone can let Hoody Proxy start it again on the next request. SSH needs no Kit process and no `sshd` in the computer, so it keeps working while the computer runs, even with the whole Kit stopped, provided the computer has an SSH public key. [Set up SSH access](/foundation/networking/ssh/#adding-ssh-key-to-computer). ## 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 | 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 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` on a second line. For example, a JSON 403 is: ```json { "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 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](/foundation/proxy/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. ```bash # 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' \ --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='' 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 -c "$COMPUTER_ID"` or # `hoody computers proxy groups permissions delete -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' hoody computers proxy groups permissions set public http -c "$COMPUTER_ID" \ --access '[8080]' --if-match 'file:v' hoody computers proxy groups permissions set public files -c "$COMPUTER_ID" \ --access false --if-match 'file:v' hoody computers proxy default set -c "$COMPUTER_ID" --default deny --if-match 'file:v' ``` ```typescript 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' }); ``` ```bash # The If-Match ETag (file:v) 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" \ -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" }' ``` ' }} bearerToken="HOODY_TOKEN" > 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`. The project form is the same with `hoody projects proxy ...` and `--project $PROJECT_ID`, for example `hoody projects proxy groups delete --project $PROJECT_ID`. ## 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](/foundation/hoody-api/realms/) isolate API access (token scoping), not networking | ## API pages | Page | Covers | |---|---| | [Proxy aliases](/api/proxy-aliases/) | Custom subdomains | | [Proxy permissions](/api/proxy-permissions/) | Project and computer access rules | | [Proxy settings](/api/proxy-settings/) | `enable_proxy` and `default` | | [Computer network](/api/computer-network/) | Proxy and VPN routing | | [Computer firewall](/api/computer-firewall/) | Network-level rules | | [Computer operations](/api/computer-operations/) | Start and stop computers | ## 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](#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` 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](#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) |