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

A computer is created with one request to a project, changed with an update and removed with a delete. Most creates answer within a few seconds, and some in under a second; a create can also take a few minutes.

You need a project ID and a server_id: the server_id field of one of your servers in hoody servers list -o json or GET /api/v1/rentals, not the rental id. Marketplace ids (GET /api/v1/servers/available) are for renting a server.

  1. In the Hub, open Computers and choose Get a computer.
  2. If a start choice is shown, keep A new computer.
  3. Check Name, Server and Project. Under More options you can set the colour, Hoody Kit, Developer kit, Autostart, an SSH key and Environment variables.
  4. Choose Get computer.

The response is the computer, running or still creating. With hoody_kit: true it has a URL for each Hoody Kit service, generated at once. Wait for running, then request the service URL; several services start on their first request:

{
"statusCode": 201,
"message": "Computer creation initiated successfully",
"data": {
"id": "890abcdef12345678901cdef",
"project_id": "67e89abc123def456789abcd",
"server_id": "63f8b0e5c9a1b2d3e4f5a6b7",
"server_name": "node-us",
"name": "dev-environment",
"status": "creating",
"hoody_kit": true,
"dev_kit": true
}
}
Terminal: https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-us.computers.hoody.com
Display: https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.computers.hoody.com
Files: https://67e89abc123def456789abcd-890abcdef12345678901cdef-files-1.node-us.computers.hoody.com
Exec: https://67e89abc123def456789abcd-890abcdef12345678901cdef-exec-1.node-us.computers.hoody.com
SQLite: https://67e89abc123def456789abcd-890abcdef12345678901cdef-sqlite-1.node-us.computers.hoody.com

These four fields are fixed at creation:

FieldDefaultWhat it decides
server_idRequiredWhere the computer runs. To move it, copy it
hoody_kittrue; false for an auth token without computers.features.hoody_kit, which gets 403 if it sends trueThe Hoody Kit services
dev_kitFollows the resolved hoody_kit valueA developer toolchain
computer_imagedebian/13The operating system. A name that does not resolve to debian/13 returns 400. To change it, see Change the OS

With hoody_kit: false, the built-in terminal, display, files and exec services are not installed. Your own HTTP servers can still be reached through Hoody Proxy; protect them with proxy permissions.

These create fields can be changed later with an update:

FieldRule
name3-100 letters, digits, hyphens and underscores, unique within the project. Omit it or send "rand" for a generated name
environment_varsSeen by new processes once applied in the computer
ssh_public_keyOmit it and the computer has no SSH access until you set a key with an update
autostarttrue by default: the computer starts when the host machine reboots
colorA hex color that marks the computer in the Hub’s lists (Colors)
Terminal window
ssh-keygen -t ed25519 -f ~/.ssh/hoody-computer-1 -N ""

When your client stops waiting or the connection drops, the create keeps running on the server, so the computer may already exist. Do not create it again under a new name: that makes a second computer.

Send the create again with the same Idempotency-Key header and the same body, within 24 hours, to get the first create’s result (every outcome). The SDK and CLI give a create 7 minutes and retry a lost connection with their own key. To retry later yourself, pass your key: headers: { 'Idempotency-Key': key } in the SDK, --idempotency-key <key> in the CLI. Without a key, list the project’s computers and look for the name.

PUT /api/v1/computers/{id} (or PATCH) changes the editable fields while the computer is running, paused or stopped. environment_vars replaces the entire map. Include every variable you want to keep; omitted variables are removed.

In the Hub, open Computers and open the computer’s menu. Choose Rename… and then Rename to change its name, or SSH key… and then Save key to set its key. To change variables, open the computer’s Overview tab, choose Edit variables under Environment variables, then Save. The Hub changes only the variables you edit and never shows saved values again.

New exec and console sessions see changed variables once env_sync.pending is false, in the update response or a later GET; a running process must re-exec. An update is refused while the computer is being claimed or quarantined, and enabling autostart can return 409; see update rules.

A delete removes the computer’s filesystem and all its data, environment variables, network configuration and firewall rules, and its service URLs become inaccessible. You do not need to stop it first. Aliases are removed with the computer, but a delete through a realm-scoped host returns 403 if an affected alias, storage share or Bot URL is outside that realm. Delete it through the unscoped host with a token that allows it, or add those resources to the realm.

A copy finishes in the background and can end failed or stopped. The SDK and HTTP examples wait for running. The CLI’s --until-done waits for the operation to complete; afterwards, run hoody computers get <copy-id> and confirm status is running. Check each needed copy’s contents before you delete the source.

  1. In the Hub, open Computers, open the computer’s menu and choose Make a copy…, then Make copy.
  2. Wait until the copy is running and check its contents.
  3. Open the source computer’s menu, choose Delete…, type the computer’s name to confirm, then choose Delete computer.

If a delete is refused, see delete refusals.

GET /api/v1/computers/{id} returns the status; runtime=true adds terminal sessions, display connections, running services with PIDs, ports and command history. Runtime information shows current activity; an on-demand service may remain stopped until its URL is requested. Only the project owner receives it, so a collaborator asks the owner.

Terminal window
hoody computers get "$COMPUTER_ID" --runtime true

A new computer usually moves from creating to running; it can later be paused or stopped. After a successful delete, GET /api/v1/computers/{id} returns 404. Delete a failed computer and try again. A host_reinstalled computer lost its files when its server was reinstalled and cannot start: delete it. See every state.

hoody computers list lists all your computers, and GET /api/v1/projects/{id}/computers one project’s, with filters.

A server holds 3 computers on the free tier, the plan’s limit on a paid subserver, and no limit by default on a rented server, unless an explicit max_computers is set. Stopped computers count. A project’s own max_computers quota is unset by default; set it with hoody projects update "$PROJECT_ID" --alias "$PROJECT_ALIAS" --max-computers 10, where --alias repeats the project’s current name. A create over a limit returns 400 and creates nothing; see limits and upgrades.

Computers themselves are not charged; see Pricing.

  • Realms: realm_ids separates computers at the API level; realms are not private networks. Give each AI agent a token restricted to its own realm, because an unrestricted token still reaches other realms. A realm ID your account does not use yet counts against its realm limit. See realm rules.
  • Recipes: create bodies for four kinds of computer and a project-to-computer flow, in Recipes.
  • Parallel creates: each create is an independent HTTP request, so a fleet or a CI/CD job can create many at once with an auth token.
  • Safe concurrent updates: send the ETag from a GET in If-Match. If the current editable settings differ from those the tag represents, the update returns 412 and saves nothing. Status changes alone do not invalidate the tag; settings restored to exactly their earlier values match again. See the update call.
  • Virtual machines: kvm: true at create requests /dev/kvm access so the computer can run full virtual machines, on a rented dedicated server only. Check kvm and kvm_note in the response, and read the computer again to confirm its current setting and status. If KVM is off, wait for creation to finish, stop the computer if needed, then send PUT /api/v1/computers/{id}/kvm with {"kvm": true} while it is stopped. Start it after the request succeeds. See Virtual Machines.

Fields, states, limits, recipes and troubleshooting: the Create, Edit, Delete reference.