# Security reference **Page:** concepts/security/reference [Download Raw Markdown](./concepts/security/reference.md) --- # Security reference Lookup detail for [Security & Permissions](/concepts/security/). ## The layer stack From bottom to top, each layer narrows the attack surface: ``` ┌─────────────────────────┐ │ Application Security │ Your responsibility (input validation, auth logic) ├─────────────────────────┤ │ Proxy Permissions │ JWT, password, IP, token, Hoody login per service ├─────────────────────────┤ │ Computer Firewall │ Ingress/egress rules the computer cannot change ├─────────────────────────┤ │ Network Control │ Optional controlled exit ├─────────────────────────┤ │ Computer Isolation │ Files, processes, memory and network kept apart ├─────────────────────────┤ │ Bare Metal Ownership │ Your hardware alone (dedicated servers only) ├─────────────────────────┤ │ Disk Encryption │ Every disk encrypted at rest ├─────────────────────────┤ │ Realm Isolation │ API-level multi-tenancy ├─────────────────────────┤ │ URL Unguessability │ 2^96 keyspace, no enumeration └─────────────────────────┘ ``` The layers fail separately: compromising one does not hand an attacker the rest. They are not fully independent, because no isolation boundary is absolute. On a rented or owned machine, bare metal ownership removes whole classes of attack even if a computer is fully taken over. On a free slice the bare metal layer is absent, and the stack is one layer shorter. ## URL unguessability ``` https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-us.computers.hoody.com └──────────┬──────────┘ 24 hex chars = 2^96 ``` | Fact | Value | |---|---| | Computer ID | 24 hexadecimal characters, 96 bits of entropy, the same keyspace as a strong encryption key | | Possible computer IDs | 2^96 = 79,228,162,514,264,337,593,543,950,336 | | Full scan at 1 billion guesses per second | 2.5 × 10^12 years, about 180 times the age of the universe (1.38 × 10^10 years) | | Certificates | Wildcard (`*.{serverName}.computers.hoody.com`), so no one can discover your computer addresses by scanning public certificate databases | | Recreating a program | Does not change the URL, because the project and computer ids in the hostname stay the same | | Cutting off a leaked URL | Set proxy permissions with a `deny` default, or replace the computer with one that has a new computer id | The security model starts at the URL, before any authentication layer runs. ## Authentication methods | Method | Mechanism | Use case | | :--- | :--- | :--- | | **Password** | HTTP Basic Auth | Quick protection for internal tools, demos | | **JWT** | Token with claims validation | API consumers, AI agents, service-to-service | | **IP whitelist** | Allow by IP address or CIDR range | Office networks, known servers, CI/CD runners | | **Token** | Exact token from a configured header, cookie, or query parameter | Machine-to-machine, webhook endpoints | | **Hoody identity** | The identity a visitor gets by signing in to Hoody, with no key material of yours | Gating a computer on logged-in Hoody users | An IP group must use the public egress range your clients come from: a private range such as `10.0.0.0/8` never matches an internet visitor's source address. ## Permission scopes **Project-level permissions** apply to every computer in the project: ``` Project "production" → deny all by default └─ Group "devops": IP 203.0.113.0/24 → allow terminal, files, display └─ Group "monitoring": Token → allow http port 8080 ``` **Computer-level permissions** apply alongside project settings for specific computers; when both documents exist, both govern and must be evaluated together: ``` Computer "public-api" → evaluated together with the project document └─ Group "world": IP 0.0.0.0/0 → allow http only └─ Group "operators": JWT → allow everything ``` | Rule | Detail | |---|---| | Per service | Each group gets access per service, not all-or-nothing | | Writes | Need `If-Match: file:v` from a prior GET: `428` without it, `412` if stale. Every write bumps the version | | Kill switch | `enable_proxy: false`: new requests answer `403` and no rule re-opens access. The computer keeps running. A computer's own `true` overrides a disabled project | | Aliases | Permissions follow the computer, not the URL: the alias and the cryptographic URL both inherit them. There is no way to lock down only the alias | The full rules are on [Proxy Permissions](/foundation/proxy/permissions/). ## Realms [Realms](/foundation/hoody-api/realms/) provide API-level isolation: through the API, a token restricted to a realm sees and acts on only that realm's computers. A realm filters the API; it is not network segmentation and does not keep computers apart on the network. Each realm-scoped API hostname sees only its realm's computers: ``` https://507f1f77bcf86cd7994390aa.api.hoody.com → sees only Realm A's computers https://507f1f77bcf86cd7994390bb.api.hoody.com → sees only Realm B's computers ``` ## Computer isolation Computers are isolated from each other. The isolation is always on: it does not depend on convention or configuration. | Area | Guarantee | |---|---| | Filesystem | Its own root filesystem, with no shared volumes by default. Computer A cannot read computer B's `/etc/passwd`, write to its `/home`, or know computer B exists on the same server | | Network | Its own network, with no shared internal segment to eavesdrop on. Outbound traffic leaves from the server's public address; a dedicated public IPv4 can't be ordered yet. Computers reach each other the same way any two machines on the internet do | | Processes | A computer sees only its own processes and cannot enumerate, signal or attach to another computer's | | Memory | Computers cannot read each other's RAM | Isolation limits a compromised computer's direct access to other computers' files and processes. It can still affect shared storage mounts and the services its credentials or network access reach, and replacing the computer does not undo those effects. Isolate the compromised computer, preserve any evidence you need, and check what its credentials, shares and network access could reach. To recover this computer, restore a known-good snapshot before deleting it. If you replace the computer instead, address any effects on shared resources separately. No isolation boundary is absolute, but the unit of compromise stays small. ## Free slice or dedicated machine | | Free server or paid subserver (shared machine) | Rented or owned machine | | :--- | :--- | :--- | | **Hardware** | Shared with other tenants | Yours alone, unless you share the server through a [pool](/foundation/servers/share/) | | **Cross-tenant side channels** | Not ruled out | None: no other tenant runs on the machine, unless you share the server through a pool | | **Noisy neighbors** | Possible | None, unless you share the server through a pool | | **Hardware performance counters** (`perf` and similar profilers) | Blocked, because they can expose timing and address information across tenants | Run under the machine's normal Linux permissions; Hoody adds no restriction | - **Dedicated machine:** no cross-tenant side channels, and nobody else rents the machine. Others' computers run on it only if you share the server through a [pool](/foundation/servers/share/). You control the server and its network configuration, and all CPU cycles, memory and disk IOPS are yours. - **Your own VMs:** you can opt in to [running your own VMs](/foundation/servers/virtual-machines/) on your own machine. - **Free tier:** it exists so you can try the whole platform for real. Treat a free server or paid subserver, both slices of a shared machine, as untrusted for production secrets, customer data, private keys and regulated data. [Renting a machine](/foundation/servers/) is the single upgrade that turns the bare metal layer back on. - **Cost:** a dedicated Hoody server is a flat monthly cost with no usage meter and no per-computer billing. Computers are light, so many can share a server. Development, staging and production can all live on one, along with anything else you want to self-host. ## Disk encryption | Fact | Detail | |---|---| | Coverage | Your disk is encrypted at rest on every Hoody machine, free-tier servers and rented machines alike. Nothing to enable, no way to opt out | | Protects against | Theft and physical seizure: a stolen disk or seized chassis holds ciphertext, so that is a hardware loss rather than a data breach | | Does not protect | Data on a running server. While the server runs, its files are readable to the services that serve your computers and to Hoody, which operates the machine | For data that must stay opaque while the server runs, encrypt it in your own code and upload the [ciphertext](/guides/private-workflows/#encrypting-files-yourself), so the key is yours and never reaches the server in the clear. ## Firewall Each computer has firewall rules, set through the API, that control traffic at the packet level. They apply outside the computer, so a compromised computer cannot modify its own firewall. | Rule type | What it controls | | :--- | :--- | | **Ingress** | Which IPs/ports can reach the computer | | **Egress** | Which IPs/ports the computer can reach | | **Protocol** | TCP, UDP, and ICMPv4 (`icmp4`) filtering | | **Default stance** | Default-allow: everything passes until you add rules, and each rule can allow, reject, or drop what it matches | You can also run iptables, nftables or ufw inside the computer, with two cautions. Turning on a firewall there, ufw included, can make the computer's Kit URLs fail with `504`; filter who reaches the computer with the computer firewall or [proxy permissions](/foundation/proxy/permissions/) instead. And the daemon keeps its per-program sandbox ingress rules in an nftables table of its own, so a tool that flushes or resets nftables removes them too. | After a flush | Result | |---|---| | A program that declares an ingress policy | Starting the program through the daemon restores its ingress rules before launch; the start fails if restoration fails | | A program already running | Keeps running and listening without its ingress filtering until the next firewall change or daemon start reinstalls the rules | | Repair | No periodic repair: restart the daemon, make a successful ingress-policy change, or start the program through the daemon, then check `GET /api/v1/daemon/programs/{id}/sandbox` on the daemon service URL before relying on that filtering. See [Program Sandbox](/kit/program-sandbox/#ingress-firewall) | ## Network exit | Fact | Detail | |---|---| | Default | Outbound traffic leaves from the server's public address, and egress to public IPv4 is permitted. A dedicated public IPv4 can't be ordered yet | | Always blocked | Private and special-use ranges; TCP and UDP ports 16, 17 and 2049; TCP ports 25, 26, 366 and 2525; and tunnelling protocols 4, 41, 47 and 132 | | Exit types | SOCKS5, HTTP or HTTPS proxies as exit nodes; block mode to prevent all outgoing traffic. DNS resolvers are set inside the computer, like on any Linux machine | | Commercial VPNs | Point a computer at any provider's internet-reachable SOCKS5 or HTTPS proxy endpoint, with no in-computer configuration | | Once configured | Direct egress to the internet is removed. The exit is enforced outside the computer's reach, so a compromised computer cannot add its own route or fall back to a direct connection | | Platform services | DNS, the package mirror and the AI gateway stay reachable on their own paths | Configure an exit on [Network Configuration](/foundation/networking/network/). Until you do, treat computer egress as open. ## Outbound requests from Kit services The rules above govern traffic your own programs open. A Kit service that makes an HTTP request on your behalf is bound separately, and more tightly: [egress](/kit/egress/) when it proxies a request, and [Run](/api/run/) when it delivers a webhook or fetches a remote package index or source. | Rule | Detail | |---|---| | Destinations | A destination the service dials itself: globally routable IPv4 only. Private, loopback, link-local, CGNAT, multicast and reserved destinations are refused, and no flag, environment variable, file or API field admits one | | DNS | Each name is resolved once and the address that was checked is the address that is dialled, so a short-lived DNS record cannot pass the check and then point elsewhere | | IPv6 | Refused: computer networking is IPv4-only, and these services enforce that themselves rather than assuming it | | Chained exit | The one exception: egress accepts a SOCKS5 upstream on the computer's own loopback, which is how [`hoody egress local start`](/kit/egress/#exit-from-your-own-machine) hands traffic to the machine you run it on. Once an upstream is in force, its far end decides where a request goes. On this side, an IPv6 literal is still refused before dispatch, a `socks5` upstream has its target resolved here, where an IPv4 address is selected, and the upstream's own address is checked by the same rules | | Run: proxy variables | Proxy environment variables in the computer do not redirect its fetches | | Run: redirects | Webhook deliveries and remote index fetches follow none. A source fetch follows at most ten http(s) hops and refuses a hop pointing at a prohibited address | | Run: refused webhook | Records one failed attempt rather than burning its whole retry budget on the same verdict | | Refusals | Visible: egress answers `403 destination not permitted`; a configured upstream proxy with no permitted address answers `502` instead of sending the request out directly | See [Destination rules](/kit/egress/#destination-rules) for the full behaviour. ## Programs and aliases An alias hides the computer ID, not the surface behind it. Two failure modes follow you across the alias: - **Metadata leakage.** Some programs embed the underlying computer ID, internal paths, hostnames or environment details in HTML, response headers, error pages or websocket handshakes. The alias hides nothing if the response body says `computer_id: 890abcdef…`. - **Surface exposure.** The alias still routes to a specific [program](/kit/). User-written programs are your responsibility; privileged control planes make the surface itself the dangerous action. | Program | Why it is safe to publish | | :--- | :--- | | **`http`** | Your web server / API. The auth and authorization are your application logic: you decide what is exposed. | | **`exec`** ([hoody-exec](/kit/exec/)) | Scripts you wrote with explicit handlers and routes. An unrestricted Exec alias also reaches the script-management API, so pin a public alias to one script: set `target_path` to its route and `allow_path_override` to `false`. Otherwise protect it with proxy permissions. | | **`pipe`** ([hoody-pipe](/kit/pipe/)) | A relay with no on-disk state, gated by proxy permissions. POST/PUT and GET stream bytes one way; `?live` broadcasts to late joiners and `?ws` pairs two peers for messages in both directions. The send, receive, share, video and progress pages use the same permission rules. Publishing a name also makes its status observable to permitted callers. | | **`tunnel`** ([hoody-tunnel](/kit/tunnel/)) | HTTP and TCP forwarding of a local service through the proxy. The `tunnel` alias reaches the Tunnel control service, which lists and terminates sessions, so protect it with proxy permissions. To publish a forwarded web application, point an `http` alias at its exposed computer port. | Publish aliases for your application routes and Pipe transfers: public sharing, business cards, embedded docs and customer-facing URLs are the intended use, and you decide what the application returns. Pin public Exec aliases to specific script routes. For Tunnel applications, publish an `http` alias targeting the exposed application port. Keep management endpoints behind [proxy permissions](/foundation/proxy/permissions/), which also give a clean URL backed by real authentication. Every other Hoody Kit program is an operator surface. Aliasing it is fine for internal use behind IP whitelists or strong auth; never publish the alias the way you would publish an API URL. For these, prefer the cryptographic URL: the 2^96 keyspace is your authentication of last resort. | Program | Why publishing the alias is dangerous | | :--- | :--- | | **`terminal`** | The alias becomes a published shell endpoint. One credential away from arbitrary command execution. | | **`files`** | Filesystem browser. Listings, downloads, and uploads against the computer's root. Path leakage is the default behavior. | | **`sqlite`** | Live database UI and SQL API. Schema, secrets, and writes, all over HTTP. | | **`display`** | Remote desktop with keyboard, mouse, clipboard read and write, and screenshots. Hijacking it hijacks the running session. | | **`code`** | Full editor with filesystem access. Extensions can execute code. Reads keys and configs. | | **`browser`** | Chromium with JavaScript evaluation, headful on its display by default. Cookies, automation, and credential interception live here. | | **`agent`** | Agent aliases are not supported. Use the standard Agent service URL and protect it with proxy permissions. | | **`cron`**, **`daemon`** | Scheduled jobs and process control. Inject a job, gain persistent execution. | | **`curl`** | HTTP request wrapper. Aliased and exposed, it becomes an open SSRF gateway with your IP and your secrets. | | **`ssh`** | SSH over the proxy. Same risk class as terminal. | An alias does not replace permissions: an alias for a privileged program (an internal operations terminal at `ops-shell.node-us.computers.hoody.com`) is public information, so give the computer [proxy permissions](/foundation/proxy/permissions/) (IP whitelist, JWT or password, default-deny) and set `expires_at`. ## Guardrails for a published alias | Guardrail | Detail | |---|---| | Unique, non-generic names | Distinctive names reduce accidental collisions, but aliases remain guessable and should be treated as public. Generic names such as `api`, `app` and `prod` are especially easy to guess. Name conflicts return `409`: scope `"server"` means the name is unavailable on that physical server; scope `"account"` means your account already uses it on a server, including this one | | `target_path` | Chooses where a bare root request lands: `target_path: "/api/v1"` sends `/` to `/api/v1` | | `allow_path_override: true` (default) | Every other path passes through as sent | | `allow_path_override: false` | The alias serves only the root, or `target_path` itself. Other paths, sub-paths and assets included, answer `404 ALIAS_PATH_PINNED`, and a parameter written in `target_path` cannot be overridden, but the visitor's method, body and other parameters still pass | | Who can open it | Neither field limits who can open the link. Scope the computer's [proxy permissions](/foundation/proxy/permissions/) for that | | Permissions | Apply them to the underlying computer: the alias and the cryptographic URL both inherit them. There is no way to lock down only the alias | | Custom domains | Default computer subdomains are covered by a wildcard certificate and never appear in Certificate Transparency logs. A hostname such as `api.mycompany.com` CNAMEd to your alias does appear in public CT logs, so it is publicly enumerable in a way `*.{serverName}.computers.hoody.com` URLs are not. Fine for intentional production exposure | | Deleting a computer | Deleting a computer also deletes its proxy aliases. Remove any custom-domain DNS records you no longer need | The computer ID is a secret; the alias is a label. Publish the label only for programs whose surface you would also publish. ## AI-generated code AI-generated code will have bugs and vulnerabilities and will make network calls you did not anticipate. That is a consequence of scale, not a failure of discipline. | Control | Detail | |---|---| | Containment | A rogue AI-generated process cannot read other computers' filesystems or signal their processes. Shared storage mounts, credentials and network access you grant remain paths to other data and services, and a writable share stays exposed to destructive code | | Program sandbox | A program you run through the daemon can be confined with a [program sandbox](/kit/program-sandbox/): a read-only filesystem, TCP port limits, resource caps and an ingress allowlist. Optional: the program runs as a daemon program under an existing non-root account with an effective `sandbox` block. Creating a computer applies no program confinement by itself | | Snapshots | Snapshot before an AI makes changes. If it breaks something, restore the snapshot instead of debugging or running a `git bisect`. A restore can take many minutes | | Network control | Configure an exit path and [firewall rules](/foundation/networking/firewall/#leave-only-the-ports-you-need-open), and the computer hits a boundary it cannot modify. Configure nothing and its egress is open | | HTTP observability | HTTP calls through your computer's service URLs pass Hoody Proxy. Use [hoody-exec](/kit/exec/) hooks to intercept or rate-limit requests to supported Kit services. Hooks do not apply to `logs`, `egress`, `workspaces` or `cdp`. What proxy logs contain and how long they are kept is in [Auditing & Data Collection](/concepts/auditing/) | | Outbound calls | Do not pass this proxy. Configure a network exit to control their path, and add logging at that exit if you need outbound observability | Computer isolation mitigates lateral movement but does not prevent application-level vulnerabilities within a computer. Supply chain attacks (compromised npm packages, malicious Docker images) remain an industry-wide challenge. ## Security postures | | Development | Staging | Production | |---|---|---|---| | Permissions | None configured | IP whitelist for office/VPN | JWT for API, password for operators, IP for infra | | URL security | Cryptographic (2^96) | Cryptographic + IP check | Cryptographic + auth required | | Firewall | Default allow | Drop every source range except the known ones | Drop unwanted ports and source ranges, minus what you keep | | Network | Direct egress by default | Proxied exit | Controlled exit | | Snapshots | | | Hourly automated | | Who can access | Only people who have the URL | Even with the URL, you must be on the right network | Every layer is active | Development suits experimentation and internal tools: with no permissions configured, the unguessable URL is the only gate. Staging adds a second factor.