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 creating, updating and deleting computers. Every field and status code is in the Computers API.

The create request body (POST /api/v1/projects/{id}/computers) accepts these fields. The last column says whether an update can change it.

FieldDefaultRuleUpdate
server_idRequiredWhere the computer runs: the server_id field (not the rental id) from your own inventory, GET /api/v1/rentals or its alias GET /api/v1/servers. Choose by geography, capacity or price. Not GET /api/v1/servers/available: its ids are for renting a server, not for placing a computerNo; use copy
nameGenerated3-100 characters: letters, digits, hyphens, underscores. Unique within the project; "rand" or no name generates oneYes
hoody_kittruetrue installs the Hoody Kit HTTP services; false gives a plain Linux computer, for minimal overhead, custom service installations or managing everything over SSH yourself. With an auth token, omission also enables Hoody Kit. If the token lacks computers.features.hoody_kit, send hoody_kit: false or the request returns 403. Recommended: hoody_kit: true, unless you specifically want a plain computerNo
dev_kittrue when hoody_kit: truetrue installs the developer toolchain; false omits it to keep the computer smaller. The editor and agent services come with hoody_kit, not with this optionNo
computer_imagedebian/13 if omitted or nulldebian/13 (Debian 13 Trixie), the base image the platform carries; a name that does not resolve to it returns 400 listing the accepted names. See Computer ImagesNo: the OS is permanent (Change the OS)
environment_varsNoneSeen by new processes once applied in the computer (Update rules)Yes: add, modify, remove
ssh_public_keyNone: no SSH access until you set oneOne per computer (SSH keys). With an auth token, installing a key also needs the resources.ssh_keys permission (403 without it); a signed-in session needs noneYes
realm_idsNoneRealmsYes, except by realm-restricted tokens
colorRandomHex color shown in the UI, with or without # (Colors)Yes
commentNoneA descriptionYes
autostarttrueStart when the host machine reboots, so services stay available across server maintenance and restarts. With false the computer stays stopped after a host reboot until you start itYes (Update rules)
aitrueAI features default to true. With an auth token lacking computers.features.ai, send ai: false or the request returns 403Yes
ramdisktrueRequests the managed /ramdisk mount where availableYes
ramdisk_scopecomputerOnly computer is accepted for now (RAM disk)No other value
kvmfalsetrue passes /dev/kvm through to run full virtual machines, on rented or dedicated servers only (Virtual Machines)Only with PUT /api/v1/computers/{id}/kvm, on a stopped computer
{
"comment": "Development environment for Project X",
"autostart": true,
"ai": true,
"ramdisk": true
}

dev_kit: true installs a developer toolchain inside the computer. Check for a tool with command -v before relying on it.

RuleTools
Node.jsA fresh image gets 26.13.1. An image that already has a Node.js 26 release keeps it; if 26.13.1 is not available, the newest 26 release is installed
Latest release at install timeGo, Rust, Bun, Nix, pkgx, GitHub CLI, Docker, the npm tools, uv, ruff, Poetry. Go falls back to 1.27.4 when the version response is not recognized
Kept when the image has themBun, Rust, Nix, pkgx, GitHub CLI; Docker when the Docker daemon, Docker Compose and Docker Buildx are all installed
From the image’s package repositoriesPython 3, pip, venv, pipx, the command-line tools, the headers. pipx is installed with pip if it is not available there
Best effort: one that fails to install is left out, and the computer is still createdYarn, pnpm, the AI coding CLIs, the npm tools, pip, venv, pipx, uv, ruff, Poetry, rust-analyzer, gopls, Delve, individual command-line tools, the development headers
  • Node.js 26 (26.13.1 on a fresh image) with npm, plus Yarn and pnpm through Corepack. If Corepack cannot be installed, Yarn and pnpm are installed with npm instead. If Corepack cannot be enabled or activated, Yarn or pnpm may not work
  • TypeScript, ts-node, tsx, ESLint, Prettier, Biome, nodemon, concurrently, npm-check-updates
  • AI coding CLIs: Claude Code, Codex, opencode, Gemini CLI (no credentials are included)
  • Bun
  • The image’s Python 3 (installed only if missing), with pip, venv and pipx, plus uv, ruff and Poetry through pipx
  • Rust (stable, through rustup) with rust-analyzer
  • Go, with gopls and Delve
  • Nix and pkgx
  • GitHub CLI, Docker Engine, Docker Compose and Docker Buildx. The Docker daemon is not running when the computer starts: the first docker command starts it. The default user can run docker without sudo
  • Command-line tools, including ripgrep, fd, bat, fzf, jq, yq, httpie, Neovim, git-lfs, delta, gdb, valgrind, Clang and LLVM, and the PostgreSQL, MySQL and Redis clients
  • Development headers (OpenSSL, libffi, zlib, SQLite, PostgreSQL, MariaDB, libxml2 and others) so native extensions compile

realm_ids assigns a computer to realms for API-level isolation. Realms are not private networks; they segregate the Hoody API. See Realms.

{
"realm_ids": ["64a2c4e9f3d5e2b6a8c7d8e1", "65b3d5f0a4e6f3c7b9d8e9f2"]
}
RuleDetail
EndpointsEach realm has its own API endpoint, https://{realmId}.api.hoody.com, so production, staging and development are separated at API level
TokensAuth tokens can be scoped to realms. An AI agent using a token limited to realm A cannot discover or manage computers in realm B
AI agentsGive each AI agent its own realm and a token restricted to it. An agent holding an unrestricted token can still reach other realms, so placing its computer in a realm is not enough on its own
Create from a realm-scoped hostThe target project must already include that realm. The scoped realm is merged into the computer’s realm_ids, and realm-restricted auth tokens are forced to it only
Realm limitA create, copy or update that brings in a realm ID your account does not use yet is refused with 400 REALM_LIMIT_REACHED when your account is at its realm limit, and nothing changes. Realms you already use are never refused

Each computer needs its own SSH public key: Hoody’s SSH Proxy routes by public key, so two computers cannot share one SSH identity. Without a key of its own, a computer has no SSH access until you set one with an update. With Hoody Kit installed (the default), Hoody Terminal still gives you a shell over HTTP. A computer created with hoody_kit: false has neither, so set an SSH key for it. SSH is useful for local tools such as VS Code Remote and rsync, but not required for day-to-day work. See SSH Access.

Terminal window
# Generate new key pair for each computer
ssh-keygen -t ed25519 -f ~/.ssh/hoody-computer-1 -N ""
ssh-keygen -t ed25519 -f ~/.ssh/hoody-computer-2 -N ""
computer_1: {"ssh_public_key": "ssh-ed25519 AAAA... (from computer-1.pub)"}
computer_2: {"ssh_public_key": "ssh-ed25519 AAAA... (from computer-2.pub)"}
{
"color": "#3498db"
}

The scheme borrows from Qubes OS, which uses color to mark security domains (red for untrusted, green for trusted). A color makes a computer identifiable in a long list without reading its name. Pick a scheme and keep to it:

SchemeColors
WebOS buildersOne per workspace or application
Security zonesRed for public-facing, green for internal services, blue for databases
Multi-user teamsOne per user or team
Environment typesYellow for development, orange for staging, green for production

On the free server and paid subservers, ramdisk: true requests temporary RAM storage at /ramdisk; ramdisk: false leaves it out. Computers running directly on a physical server do not receive the managed mount. See /ramdisk for usage patterns and memory balancing.

RuleDetail
MemoryAllocated as you write, so an empty /ramdisk consumes none. It counts against your server’s memory, not its disk space
CapacityOn servers with the managed RAM disk, one memory pool is shared by your computers on that server: 512 MiB by default, capped at 50% of the server’s memory, not adjustable
LifetimeSurvives computer restarts; lost when the host machine reboots
ramdisk_scopeAccepts computer. Sharing /ramdisk across a project’s computers is temporarily unavailable: a request with ramdisk_scope: project is refused, and /ramdisk stays private to each computer. Share files through storage shares instead
UsesCaches, build artifacts and temporary processing that needs the speed
RuleDetail
autostartEnabling it returns 409 Conflict until a network policy is in force and any hard access suspension is lifted
realm_idsAuth tokens restricted to realms cannot change it
Environment variablesChanges do not generally require a restart: after a successful live sync, new exec and console processes see them. The computers env endpoints also update /etc/environment for new SSH and console logins

environment_vars replaces the entire map. Include every variable you want to keep; omitted variables are removed.

# Switch from staging to production
PATCH /api/v1/computers/{id}
{
"environment_vars": {
"NODE_ENV": "production",
"API_BASE_URL": "https://api.mycompany.com"
}
}
# Assign the computer to the production API realm
PATCH /api/v1/computers/{id}
{
"realm_ids": ["64a2c4e9f3d5e2b6a8c7d8e1"]
}

A delete is irreversible and takes the computer’s snapshots with it. Its aliases, status logs, SSH keys and storage shares are deleted with it too. If DELETE /api/v1/computers/{id} is refused, check:

CheckRule
PermissionsYou own the computer, and your auth token has computers.delete and a realm that covers the computer
Default computerYour account’s auto-provisioned default computer cannot be deleted unless it has expired (for example, after its host was reinstalled)
Mid-claimA computer still claiming is refused until it reaches running. Retry shortly
QuarantineA quarantined computer is normally refused. The quarantine restriction does not apply if it is host_reinstalled or its failure_reason.code is CREATE_NOT_STARTED; other delete restrictions still apply. Otherwise, contact support

hoody_kit: true installs the full Hoody Kit HTTP stack. Installation is part of the create. See The Hoody Kit for complete service documentation. Some of the services:

ServiceWhat it does
Hoody Terminal (hoody-terminal)Web-based terminal
Hoody Displays (hoody-display)Full desktop environment
Hoody Browser (hoody-browser)Chromium and Firefox automation
Hoody Files (hoody-files)Filesystem access
Hoody SQLite (hoody-sqlite)Database and KV store
Hoody Exec (hoody-exec)Scripts as HTTP APIs
Hoody cURL (hoody-curl)HTTP request wrapper
Hoody Daemon (hoody-daemon)Process management
Hoody Notifications (hoody-notifications)Alerts
Hoody Code (hoody-code)VS Code instances
Hoody Cron (hoody-cron)Scheduled task runner
Hoody Pipe (hoody-pipe)Data streaming between services
Hoody Agent (hoody-agent)AI coding agent with a browser terminal interface and an HTTP API

A common create, run and stop path; the table adds the exceptional states.

creating → running → (paused) → stopped
↓ ↑
(can pause) (can restart)
StateDescriptionTransitions available
claimingBeing made ready for you→ running (automatic)
creatingComputer being provisioned→ running (automatic)
runningComputer is active→ stopped, paused
pausedComputer suspended→ running (resume)
stoppedComputer is stopped→ running (start)
failedCreation or operation failedDelete it (cleanup)
copyingBeing created as a copy→ running (when complete); → stopped if the copy was made with copy_network_rules: true and network setup or automatic start fails
host_reinstalledIts server was reinstalled, and its files are gone. Left out of computer lists unless include_expired=true; it can’t start or run commandsRemoved (delete it)

Deletion has no state to poll. After a successful DELETE /api/v1/computers/{id} returns 200, the computer is gone and GET /api/v1/computers/{id} returns 404; do not wait for a deleted status.

Read the current state:

GET Get computer status
/api/v1/computers/{computer_id}
Click "Run" to execute the request

Managing Computers covers state transitions.

GET /api/v1/computers/ lists all computers for your account, and GET /api/v1/projects/{id}/computers the computers in one project. Add runtime=true to GET /api/v1/computers/{id} for live runtime information. runtime_info.services includes service status and PIDs; runtime_info.network_services includes listening ports. In the list, page and limit page the results, realm_id filters by realm, and sort_by and sort_order sort them (list call).

GET List all computers for your account
/api/v1/computers/
Click "Run" to execute the request
GET List computers in a specific project
/api/v1/projects/{project_id}/computers
Click "Run" to execute the request
GET Filter and paginate computers
/api/v1/computers/
Click "Run" to execute the request
GET Get computer with runtime information
/api/v1/computers/{computer_id}
Click "Run" to execute the request
LimitValue
Computers per server3 on a free server, the plan’s limit on a paid subserver, or an explicit max_computers where one is set. Rented servers have no limit by default. Stopped computers count; failed and deleted ones do not (Pricing)
Over the server limit400 SERVER_COMPUTER_LIMIT; nothing is created. Delete a computer on that server, or upgrade when the error offers it in data.upgrade
Computers per projectThe optional max_computers quota, unset by default, so there is no per-project cap unless you set one. Read it with GET /api/v1/projects/{id}; over it, a create returns 400 PROJECT_COMPUTER_LIMIT
Aliases per serverBy default, 3 on a free server, 50 on Plus, 250 on Pro, and 5,000 on a rented or bare-metal server. An explicit server limit takes precedence. Over the limit, creating an alias returns 422 with data.field set to proxy_alias_limit and the same data.upgrade kinds (Alias limit reached)
Platform-wideNone, so you can create as many projects as you need
Stopped computersNot charged themselves, but they count toward the server limit and keep their files on its disk. Delete computers you no longer use
data.upgradeWhat to do
{"kind": "buy_paid_subserver"}, on a free serverBuy a paid subserver and create the computer there
{"kind": "upgrade_subscription", "subscription_id": "..."}, on a paid subserver whose plan can growUpgrade that subscription
No upgrade fieldDelete a computer, or use another server

If the first attempt failed without leaving a computer, retrying runs creation again. Otherwise, repeating the same Idempotency-Key and body within 24 hours replays the result with the Idempotent-Replayed: true header:

The first createThe answer
Succeeded201 with the computer
Stopped before finishing409 COMPUTER_CREATE_INTERRUPTED, with the computer it made in data.computer_id. Check its status, and delete it if you do not want it
FailedIts error
Succeeded, but its computer was since deleted404

The SDK and CLI send the same key again when they retry after a lost connection, so a retry returns the first create’s computer instead of making a second one; while that create is still running, they wait and ask again. A create that repeats a name in use answers 409 COMPUTER_NAME_IN_USE and, when you can see it, the existing computer’s id in data.computer_id. Key format and in-progress answers: the create call.

Each recipe is a complete create request body. Replace server_id and ssh_public_key with your own.

The full Kit stack, AI enabled, autostart on, and a color for the UI. Use it as a day-to-day working computer that comes back automatically after a host reboot.

POST Create a development computer
/api/v1/projects/{project_id}/computers
Click "Run" to execute the request

Scoped to a single realm, on debian/13, with the app’s environment set at creation.

POST Create a production API computer
/api/v1/projects/{project_id}/computers
Click "Run" to execute the request

Then create a proxy alias for a clean URL, set proxy permissions for authentication, and configure firewall rules for security.

A computer that does not come back after a host reboot, for backup jobs you run occasionally.

POST Create a minimal utility computer
/api/v1/projects/{project_id}/computers
Click "Run" to execute the request

For AI orchestration, with the provider keys passed as environment variables.

POST Create an AI agent computer
/api/v1/projects/{project_id}/computers
Click "Run" to execute the request

The Hoody Agent service is then reachable at:

https://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-us.computers.hoody.com

Create a project, pick a server, create a computer, and confirm it is running. The SSH key must be the full contents of a public key file, such as ~/.ssh/acme-frontend.pub; a shortened key is refused. Set SSH_PUBLIC_KEY to it for the SDK, HTTP and URL tabs. A key can be on one computer only.

Set PROJECT_ID, SERVER_ID and COMPUTER_ID from the responses of steps 1 to 3 (the project’s id, your active rental’s server_id, the new computer’s id).

After creation, repeat the status request until data.status is running. If it becomes failed, inspect failure_reason and follow Troubleshooting. Open service URLs only after the computer is running and its services are ready.

Terminal window
# 1. Create a project
hoody projects create --alias "client-acme" --color "#e74c3c"
# 2. Check your servers: use the server_id field, not the rental id
hoody servers list -o json
# 3. Create a computer
hoody computers create --project "$PROJECT_ID" \
--server-id "$SERVER_ID" \
--name "acme-frontend" \
--hoody-kit \
--ssh-public-key "$(cat ~/.ssh/acme-frontend.pub)"
# 4. Verify it's running
hoody computers get "$COMPUTER_ID"
# 5. Use these URLs after the computer and services are ready:
# https://{projectId}-{computerId}-terminal-1.{server}.computers.hoody.com
# https://{projectId}-{computerId}-display-1.{server}.computers.hoody.com

In the Hub, open Computers, choose Get a computer, select the project and server, configure the options, then select Get computer. To rename a computer, open its menu, choose Rename…, enter the new name, then select Rename. To delete it, choose Delete…, enter its name to confirm, then select Delete computer.

A computer’s base image cannot be changed. Creation currently supports debian/13. To start with a clean Debian 13 computer, create another computer, transfer the data you need, verify it, then delete the old one. You can transfer data through storage shares or a manual copy.

PracticeWhy
Do nothing special for speedA plain create is already the fastest path: some finish in under a second without any option, and one that returns a computer already running needs nothing more
Default to debian/13Unless you have a specific requirement: stability, security updates and package availability
Set autostart by priorityUse autostart: true for services that must return after a host reboot. Use autostart: false when you want to start the computer yourself after a reboot. Stop development computers explicitly to release their running resources between sessions
Keep snapshots of production computersFor quick rollback. A snapshot is not a backup against deletion or server loss: it stays on the computer’s server, and deleting a computer permanently deletes its snapshots. For disaster recovery, also copy the computer onto another server
Create in parallelCreates can run in parallel, subject to your account’s create rate limit and each server’s capacity. Handle 429 responses and wait for Retry-After before retrying. Give each intended computer its own Idempotency-Key and reuse that key for its retries
Automate with CI/CDCreate an auth token, store it as a GitHub secret, and call curl from your workflow. Creation is an HTTP POST, so it works in any CI/CD system
TaskCall
Create a computerPOST /api/v1/projects/{id}/computers
List all computersGET /api/v1/computers/
List a project’s computersGET /api/v1/projects/{id}/computers
Get computer detailsGET /api/v1/computers/{id}
Update computer configurationPUT or PATCH /api/v1/computers/{id}
Delete a computer permanentlyDELETE /api/v1/computers/{id}
Start, stop, pause, resumeComputer Operations
Project managementProjects
SymptomCauseWhat to do
Status stays creatingCreates take a few seconds, some a few minutes. Complex images and the first creation on a server take longerPast 2 minutes, check with hoody servers list -o json or GET /api/v1/rentals that the rental is active. With a full-account signed-in session on the base API domain, you can also inspect server.computer_capacity for your current free server. API tokens, HTTP Basic and realm-scoped requests omit this field. Past 5 minutes, try deleting and recreating the computer, or contact support with its computer_id. If a create is refused with SERVER_COMPUTER_LIMIT, use the error’s capacity details to choose another server or free a slot
status: "failed", right away or laterServer out of capacity (CPU or RAM), network issues. An unknown image or a full server or project quota is a 400 at create instead, and nothing is madeRead failure_reason (CREATE_NOT_STARTED, CREATE_FAILED or COPY_FAILED) with GET /api/v1/computers/{id}, and choose a different server if it is full. For CREATE_NOT_STARTED, delete and recreate the computer. For other failures, try deleting it before recreating; if deletion is refused because it is quarantined, contact support with its computer_id
Create returns 400 listing imagesThe name does not resolve to a base image the platform carries, debian/13Shorthand is normalized: debian, debian-13 and debian:13 all resolve to debian/13
409 COMPUTER_NAME_IN_USE on create or updateThe name must be unique within the projectChoose another name, or use the computer in data.computer_id
409 SSH_PUBLIC_KEY_IN_USE on create or updateThe key is on another computer; it cannot be reusedGenerate a new key pair
Update returns 422 with error: "Validation Error"The request does not match the schema, for example an invalid hexadecimal color or malformed realm_idsCorrect the invalid field and retry. Fixed fields such as computer_image, hoody_kit and server_id are ignored by updates; create another computer to change them
Service URLs return errors after creationNot running yet, services still initializing, or hoody_kit not enabledCheck GET /api/v1/computers/{id} shows status: "running", then wait 30-60 seconds after it. Check ?runtime=true lists the services in runtime_info, and that "hoody_kit": true