Skip to content

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

Hoody.com

Lookup tables for proxy aliases. Every route, field and response is also in the Proxy Aliases API.

FieldRule
computer_idRequired on create. The computer the alias routes to; you must own it. Fixed after create: to repoint, delete the alias and create a new one for the new computer
alias3 to 61 characters, see naming rules. Omit it, or send null or false, for a generated, unique 48-character hexadecimal name such as a3f9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3
programRequired on create. See programs
port1 to 65535, for http and https: the port your server listens on inside the computer
indexThe instance of a built-in program, default 1. For http and https it is read as the port
target_pathLanding path of a root request, with any query written in it. Up to 2048 characters; a missing leading / is added. Spaces, percent escapes, non-ASCII characters, # fragments, and . or .. path segments are rejected with 400. See path routing
allow_path_overrideDefault true. See path routing
expires_atSee expiration
enabledDefault true on create. Set it with PATCH /api/v1/proxy/aliases/{id}/state (enable, disable) or in an update

An update changes program, port, index, target_path, allow_path_override, expires_at, alias and enabled, and only the fields you send. The target computer cannot be changed.

Generated URLAlias
Form{projectId}-{computerId}-{service}-{instance}.{server}.computers.hoody.com{alias}.{server}.computers.hoody.com, where {server} is where the computer runs
CreatedAutomatically, for every program the computer runs, one per serviceBy you, one program each
GuessingUnguessable: the two IDs are 48 characters, so sharing the URL is what grants accessGuessable if the pattern is known, and open to enumeration
Typing and brandingCannot be typed, remembered or printed on a business cardShort, typeable, brandable; a CNAME target for your domain
AccessThe computer’s proxy permissionsThe same permissions, applied the same way
SuitsDevelopment, collaboration and internal toolsPublic APIs and web services, with permissions

Creating an alias leaves the generated URL working. A generated URL shared before permissions are set lets anyone holding it reach the service; see open by default.

program is required because one computer runs several services and the alias names the one it routes to. It must be a built-in Hoody program or a transport protocol (http, https); any other value is rejected.

The Agent program cannot be reached through a proxy alias, even though the create request accepts program: "agent". Use its generated computer URL instead. The create request also accepts program: "ssh", but such an alias never routes either. Connect over SSH with the computer’s SSH hostname or the shared endpoint ssh.{server}.computers.hoody.com. See which hostname to use.

programRoutes toInstance or port
http, httpsA web server or API you run inside the computer, such as Node.js, Python or GoA target port, the port your server listens on (3000, 8080, 5000), is required: send port (recommended), a program such as http-3000, or index. Without one the create is refused with 400 PORT_REQUIRED. port wins over a port in program, which wins over index
execHoody Exec scripts as APIs, see script routingindex, default 1
terminalThe terminal interfaceindex, default 1, so {"computer_id": "…", "program": "terminal"} is valid
displayThe desktop environmentindex, default 1
codeThe code editor interfaceindex, default 1

Switching an alias from a built-in program to http or https needs a port in the same update. Two http aliases on ports 3000 and 8080, such as frontend and backend, reach two servers in one computer.

RuleDetail
Length3 to 61 characters
CharactersLowercase a-z, digits 0-9 and hyphens; pattern ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
Start and endA letter or digit
Reserved exactlycomputers and containers
Reserved servicesegress, workspaces, workspace and os, as the whole label or followed by a hyphen. os, os-admin and workspace-2 are refused; egressmyapp and ostrich are fine, because the match is on a label boundary
Computer URL shapesRefused: anything starting with the {projectId}-{computerId} form (two 24-hex-character labels), or that shape after an egress-, workspaces- or proxy- prefix
Router namesapi, admin, system, internal: created, never routed, see below

Valid: my-api, staging-frontend, app-v2, prod. Invalid: -myapp (starts with a hyphen), my_api (underscore), MY-APP (uppercase).

api, admin, system and internal are reserved by the reverse proxy on the same label-boundary rule: the bare word, and anything starting api-, admin-, system- or internal-, never routes. apiary and administer are distinct labels and route normally.

The create call does not enforce this. "alias": "api-v1" returns 201 with a url that never routes, with no error or warning. If a customer domain already points at api-v1.node-us.computers.hoody.com or admin-dashboard.node-us.computers.hoody.com, DNS resolves and the request dies at the proxy: rename the alias to a form that does not lead with a reserved word, such as v1-api or ops-dashboard, and repoint the CNAME. The customer domain itself can be anything.

A name is unique across a physical server and all its subservers, across every account, and within your account across all servers. Another account can use the same name on a different physical server. Your own duplicate returns 409 ALIAS_IN_USE with data.scope "account"; a conflict on the physical server or any of its subservers returns "server".

To find a free name, add your company or an identifier (acme-api, my-app-prod, my-app-eu), or let Hoody generate one. Long, specific names (acme-prod-api-v2-us-2025) are harder to guess than api or app, but only proxy permissions stop a guess from granting access.

Each server has an alias limit. Disabled and expired aliases still count, but aliases of deleted computers, computers whose server access has expired, or computers whose owner no longer holds the server do not. Each subserver has its own count, separate from its parent and other subservers. Pricing lists the current limits.

ServerAliases
Free server3
Paid subserverThe plan’s limit: 50 on Plus, 250 on Pro
Rented server5000 by default

A create over the limit creates nothing and returns 422. The error has no code of its own: recognise it by data.field = proxy_alias_limit.

{
"statusCode": 422,
"error": "Validation Error",
"message": "Alias limit reached: this server has reached its limit of 3 aliases. Delete one, or upgrade for more.",
"data": {
"field": "proxy_alias_limit",
"current_count": 3,
"limit": 3,
"server_type": "slice",
"upgrade": { "kind": "buy_paid_subserver" }
}
}
data.upgradeWhat to do
{"kind": "buy_paid_subserver"}, on a free serverBuy a paid subserver and create the alias for a computer there
{"kind": "upgrade_subscription", "subscription_id": "..."}, on a paid subserver whose plan can growUpgrade that subscription
AbsentDelete an alias on that server (DELETE /api/v1/proxy/aliases/{id}), or create the alias for a computer on another server

target_path supplies the destination of a root request (/), including any query written in it; it is never a prefix for other paths. allow_path_override applies the same way to the alias hostname and to a custom domain pointed at it.

Do not put terminal_id, display, browser_port, id, workspaces_id, or a parameter already set by the selected service in target_path. For both open and pinned aliases, a request served from such a target returns 404 ALIAS_TARGET_QUERY_FORCED_KEY. Select the instance with index.

With true, the default, every path is forwarded as sent. A root request lands on target_path, with its query followed by the visitor’s own parameters:

# allow_path_override: true, target_path "/api/v1"
https://my-api.node-us.computers.hoody.com/ → /api/v1 (target_path)
https://my-api.node-us.computers.hoody.com/api/v1/users → /api/v1/users (forwarded as sent)
https://my-api.node-us.computers.hoody.com/admin → /admin (forwarded as sent)

With false, the alias serves only the root or target_path itself. A request the proxy permissions refuse gets their answer. One they admit:

  • a request to /, or to target_path, lands on target_path, and one trailing slash is accepted;
  • any other path, sub-paths and assets included, gets 404 with the code ALIAS_PATH_PINNED and the message “This alias serves only its root and its target path”;
  • a query parameter written in target_path keeps its value, and a visitor’s parameter of the same name is dropped;
  • a visitor’s instance selector, such as terminal_id, display or id, does not replace the one the proxy sets;
  • the method, request body, other query parameters, WebSocket upgrade and Range header pass, so a pinned alias can front one endpoint that takes a POST with a JSON body.
# allow_path_override: false, target_path "/api/v1/status?format=json"
https://status.node-us.computers.hoody.com/ → /api/v1/status?format=json
https://status.node-us.computers.hoody.com/?format=xml → /api/v1/status?format=json (target_path's value wins)
https://status.node-us.computers.hoody.com/?verbose=1 → /api/v1/status?format=json&verbose=1
https://status.node-us.computers.hoody.com/api/v1/status → /api/v1/status?format=json (target_path itself)
https://status.node-us.computers.hoody.com/api/v1/status/ → /api/v1/status?format=json (one trailing slash)
https://status.node-us.computers.hoody.com/api/v1/status/x → 404 ALIAS_PATH_PINNED (sub-path)
https://status.node-us.computers.hoody.com/users → 404 ALIAS_PATH_PINNED

An interactive kit (terminal, code, browser, files), an app that loads CSS, JS or images, and an API with several routes need true. Neither field controls who can open the alias: anyone with the link can, unless proxy permissions say otherwise. Permissions authenticate per program and port, with no path selector.

A web app on an http service (http-<port>, or plain http or https) reached through an alias receives the host the visitor typed in Host: the alias hostname, or a custom domain pointed at it. An app that checks Host against an allow-list must list the alias and every custom domain, or it refuses the request: allowedHosts in the Vite or webpack dev server, ALLOWED_HOSTS in Django, an nginx server_name, a Caddy site address.

Hoody’s own kits receive their computer URL in Host. X-Forwarded-Host always carries the host the visitor typed. See Which Host header does my app receive?.

ValueCreate (POST)Update (PATCH)
ISO 8601 string, such as "2027-07-12T00:00:00.000Z"YesYes
Unix timestamp in seconds or milliseconds, such as 1815350400NoYes
null, no expirationYesYes

Prefer ISO 8601 everywhere. Non-null expiration dates must be strictly in the future; a past or current date returns 400. On update, numeric 0 also clears expiration; prefer null to express no expiration. After expires_at passes, the alias stops routing and answers 404 to every request. The configuration is kept: clear expires_at and set enabled: true to restore routing. Expired aliases still count toward the alias limit, and expired=true lists them.

Uses: a demo environment that ends with a customer trial, an event-specific URL, a beta URL that expires when you move to production.

ChangeWhen it reaches the alias URL
Update, disable, enableUsually within about 30 seconds, sometimes longer. Until then the alias keeps its previous behavior
RenameAs an update; the old name may keep serving until then
DeleteUsually within about 30 seconds. Your account can reuse the name then: recreating it earlier can return 409, so retry after a short wait. Other accounts must wait out a 90-day hold (lifecycle)

A disabled alias answers 404 and keeps its configuration, so you can take an API offline for maintenance and bring it back.

EventEffect on aliases
Delete the computerIts aliases are deleted too, and their URLs stop resolving shortly after. You do not need to delete them first. The names are held for your account for 90 days, possibly on every server; to reuse one, create a new alias with that name for the new computer
Delete an aliasPermanent. For 90 days after release, another account cannot claim the name on the same physical server or any of its subservers; a name released when its computer is deleted may be held on every server. You can reuse your released name once deletion finishes, provided no other conflict applies. Another account may claim the name after the hold, so remove obsolete CNAME records and do not rely on long-lived cookies or credentials on an alias address
Computer stoppedYou can still create aliases for it. Requests fail until you start the computer, so you can set up production URLs before deployment
Snapshot and restoreAliases belong to the account, not to the computer. Restore a snapshot of computer A into computer B and an alias such as my-app still points to A; to route to B, delete it and create one for B’s ID
Custom domainsGET /api/v1/proxy/aliases/{id} shows the alias, not which domains CNAME to it: that is in your DNS provider. Keep your own record of CNAME mappings (a spreadsheet, a wiki, infrastructure as code)
Several aliases, one serviceAllowed: several names with the same computer_id and program, for versions (v1-api and v2-api) or several brand domains

An alias for program: "exec" gives the whole script tree a short hostname, and the path you request is the route, exactly as on the generated -exec-1 URL. Add target_path to land somewhere other than the script root.

# Scripts in the computer
api/users.ts
api/posts.ts
webhooks/stripe.ts
# Access by path
https://my-scripts.node-us.computers.hoody.com/api/users → runs api/users.ts
https://my-scripts.node-us.computers.hoody.com/webhooks/stripe → runs webhooks/stripe.ts

Do not put a label in front of an alias: https://api.my-scripts.node-us.computers.hoody.com/users is a different hostname, not a shorter spelling of the one above, and nothing routes. A dot is not a legal alias character.

Hoody Exec keeps per-subdomain script trees (scripts/<subdomain>/…) and reads the subdomain from Host. Through an alias, Hoody Exec receives its computer URL ({projectId}-{computerId}-exec-{index}.{server}.computers.hoody.com) in Host, not the alias name, so the subdomain is always default. By default, an alias with "index": 1 searches scripts/default/1/, then scripts/default/, then scripts/1/, then the scripts root. A regular .exclusive file in scripts/default/1/ restricts lookup to that instance folder. See Hoody Exec.

Every status of every route is on the Proxy Aliases API page.

Status and messageCauseWhat to do
400 Bad Request; data.reserved_alias or data.reserved_prefix names a reserved word, data.field alias a computer URL shapeA reserved name or prefix, or a computer URL shapePick a name that follows the naming rules
400 PORT_REQUIREDAn http or https alias without a port, on create or when switching from a built-in programSend port, or use http-3000
404 ALIAS_PATH_PINNED, “This alias serves only its root and its target path”A path other than / or target_path under allow_path_override: falseUse true, or link to the root
404 at the alias URLThe alias is disabled, expired or deletedenable it, or clear expires_at and set enabled: true
409 ALIAS_IN_USE, “Alias is already in use.”data.scope "server": another account holds the name on this server, or a release hold prevents its reuse. "account": your account holds it, on any server, this one included; "account" is reported when both applyChoose another name or a suffix (my-app-v2, my-app-prod). For "account", delete or rename your alias; list without filters to find it, since it can be on another project or server
409 right after a deleteThe delete has not reached the alias URL yetRetry after a short wait
409 Conflict on create, update or delete, message starting computer_finalizingThe alias’s computer is still being set upRetry shortly
422 “Alias limit reached: …”The server holds its limit of aliasesSee the alias limit
{
"statusCode": 409,
"error": "ALIAS_IN_USE",
"message": "Alias is already in use.",
"data": { "field": "alias", "value": "my-app", "scope": "server" }
}
SymptomCauseWhat to do
The alias does not routeDisabled, computer stopped, service not started, or permissionsCheck enabled: true with GET /api/v1/proxy/aliases/{id}, then status: "running" with GET /api/v1/computers/{id}, then that the service is started in the computer. Open the generated URL first to rule out permissions
Created with 201, but the URL never routesThe name equals api, admin, system or internal, or starts with one of those words followed by a hyphenRename it; see names the router refuses
A custom domain does not reach the alias yetDNS propagation: CNAME changes take 5 to 60 minutesWait, test from several locations, and check with dig api.mycompany.com that it points to the alias
Pages load but CSS, JS or other routes answer 404allow_path_override: falseSet it to true
Your app refuses requests through the aliasIt checks Host against an allow-listAdd the alias and your domains, see Host header

Each body goes to POST /api/v1/proxy/aliases: it is the create request the guide shows in CLI, SDK, HTTP and URL form.

A permanent alias whose root lands on the API base path, with every other route still reachable:

{
"computer_id": "890abcdef12345678901cdef",
"alias": "prod-api",
"program": "http",
"port": 3000,
"target_path": "/api/v1",
"allow_path_override": true,
"expires_at": null
}
https://prod-api.node-us.computers.hoody.com/ → the computer's /api/v1
https://prod-api.node-us.computers.hoody.com/users → /users (forwarded as sent)

v1-api on one computer, v2-api and beta-api on another, all "program": "http", "port": 3000:

https://v1-api.node-us.computers.hoody.com → old version (computer_id 890abcdef12345678901cdef)
https://v2-api.node-us.computers.hoody.com → new version (computer_id 890abcdef12345678901cdee)
https://beta-api.node-us.computers.hoody.com → beta, same computer as v2

When ready, delete v1-api and rename v2-api to v1-api, or update client references.

  1. Develop on the generated URL.
  2. Create a staging alias for team testing, such as staging-myapp (https://staging-myapp.node-us.computers.hoody.com).
  3. Restrict staging to the office with an IP group, the first write below.
  4. Test on staging-myapp.node-us.computers.hoody.com with your team, clients and QA.
  5. Snapshot the computer when ready.
  6. Create the production alias, such as myapp (https://myapp.node-us.computers.hoody.com).
  7. Point your domain at it: api.mycompany.com CNAME myapp.node-us.computers.hoody.com. The result is https://api.mycompany.com, with automatic SSL.
  8. Require a JWT for production, the second write below.
  9. Production is live. If something goes wrong, roll back to the snapshot.

Steps 5 and 9, snapshot and rollback. A restore replaces the computer’s current state with the snapshot. Every field and response is on the Computer Snapshots API.

In the Hub, open Computers, select the computer and open Backups. Choose Take snapshot, enter its name and press Take snapshot. To roll back, choose Restore on that snapshot and confirm with Restore computer.

In the Hub, open Computers, select the computer and open Ports & addresses. Under Aliases, choose Create alias, enter your app’s port in Port and the alias name in Alias, then choose Create alias. Use staging-myapp for step 2 and myapp for step 6.

Terminal window
# Step 5: snapshot the tested computer
hoody snapshots create -c "$COMPUTER_ID" --alias 'pre-prod-2025-11-09'
# Step 9 rollback: the snapshot's name is its alias, sanitized
hoody snapshots restore 'pre-prod-2025-11-09' -c "$COMPUTER_ID" -y

Both aliases share the computer’s one permissions document. These writes (PUT /api/v1/computers/{id}/proxy/permissions) replace the whole document, so each needs the current etag in If-Match (428 without it, 412 when it is stale). The CLI, SDK and URL forms of the same write are in Give one computer its own rules.

Step 3, office only. Replace 203.0.113.0/24 with your office’s public IP range:

Terminal window
CURRENT_ETAG=$(curl -s "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/proxy/permissions" \
-H "Authorization: Bearer $HOODY_TOKEN" | jq -r '.data.etag')
curl -X PUT "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/proxy/permissions" \
-H "Authorization: Bearer $HOODY_TOKEN" \
-H "If-Match: $CURRENT_ETAG" \
-H "Content-Type: application/json" \
-d '{
"project": "'"$PROJECT_ID"'",
"computer": "'"$COMPUTER_ID"'",
"groups": {
"office": { "type": "ip", "range": "203.0.113.0/24" }
},
"permissions": {
"office": { "http": [3000] }
},
"default": "deny"
}'

Step 8, JWT for production:

Terminal window
CURRENT_ETAG=$(curl -s "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/proxy/permissions" \
-H "Authorization: Bearer $HOODY_TOKEN" | jq -r '.data.etag')
curl -X PUT "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/proxy/permissions" \
-H "Authorization: Bearer $HOODY_TOKEN" \
-H "If-Match: $CURRENT_ETAG" \
-H "Content-Type: application/json" \
-d '{
"project": "'"$PROJECT_ID"'",
"computer": "'"$COMPUTER_ID"'",
"groups": {
"customers": {
"type": "jwt",
"secret": "a-long-random-signing-key-with-32-plus-chars",
"algorithm": "HS256",
"sources": ["header:Authorization"]
}
},
"permissions": {
"customers": { "http": [3000] }
},
"default": "deny"
}'

Replace the secret with your own random signing key of at least 32 characters, and keep it private.

Development: https://67e89abc123def456789abcd-890abcdef12345678901cdef-exec-1.node-us.computers.hoody.com (generated URL)
Staging: https://staging-myapp.node-us.computers.hoody.com
Production: https://api.mycompany.com (JWT auth, custom domain)

After step 8, the full-replacement write has removed the office group and installed the customers JWT group: both HTTP aliases require a JWT, and the exec URL is denied by the default policy. When staging and production need different policies, use separate computers or different program or port rules.

List, then update each id. This gives every alias of one project a new landing path:

Terminal window
LIST=$(hoody proxy aliases list --project-id '67e89abc123def456789abcd' -o json) || exit 1
for ID in $(jq -r '.aliases[].id' <<<"$LIST"); do
hoody proxy aliases update "$ID" --target-path /v2 || echo "update failed: $ID" >&2
done
TaskHTTPCLISDK
CreatePOST /api/v1/proxy/aliaseshoody proxy aliases createclient.api.proxy.aliases.create
List, filtered by project_id, computer_id, realm_id, enabled or expiredGET /api/v1/proxy/aliaseshoody proxy aliases list, with --project-id, --computer-id, --realm, --enabled or --expired true; --watch redraws itlist
Details, with project, computer and server_nameGET /api/v1/proxy/aliases/{id}hoody proxy aliases getget
Change fieldsPATCH /api/v1/proxy/aliases/{id}hoody proxy aliases updateupdate
Enable or disablePATCH /api/v1/proxy/aliases/{id}/statehoody proxy aliases enable, disableenable, disable
DeleteDELETE /api/v1/proxy/aliases/{id}hoody proxy aliases delete (asks first; -y skips)delete

Related: proxy permissions control who can open an alias, and computer operations cover the computer lifecycle.