Create, Edit, Delete
Section titled “Create, Edit, Delete”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.
- In the Hub, open Computers and choose Get a computer.
- If a start choice is shown, keep A new computer.
- Check Name, Server and Project. Under More options you can set the colour, Hoody Kit, Developer kit, Autostart, an SSH key and Environment variables.
- Choose Get computer.
hoody computers create --project "$PROJECT_ID" --server-id "$SERVER_ID" --name dev-environment --hoody-kitimport { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const computer = await client.api.computers.create(process.env.PROJECT_ID!, { name: 'dev-environment', server_id: process.env.SERVER_ID!, hoody_kit: true});console.log(computer.data.status);curl -X POST "https://api.hoody.com/api/v1/projects/$PROJECT_ID/computers" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "dev-environment", "server_id": "'"$SERVER_ID"'", "hoody_kit": true}'Creates the computer, sent through another running computer’s curl-1 (OTHER_COMPUTER_ID).
https://PROJECT_ID-OTHER_COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/projects/PROJECT_ID/computers&method=POST&bearer_token=HOODY_TOKEN&json={"name":"dev-environment","server_id":"SERVER_ID","hoody_kit":true}&response=transparentOne request, one link
cURL runs inside your computer and can wrap any HTTP request into a single GET URL. The call stops being something you need a client for and becomes something you can paste into a browser, send in a chat, bookmark, schedule with cron, or drop into a no-code tool.
Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials. It also appears in the cURL service's request log, not only the target's. Prefer a delegated token with minimal permissions and an expiry: see API tokens.
Slashes, colons and braces pass through as they are. The one character you must
encode is an & inside a value, which happens when the wrapped URL
carries its own query string. Left raw it ends the value early, and the rest is
read as cURL's own parameters, so you get a 200 on a request you did
not make.
How the wrapping works Chaining calls into one link Turning a link into a shortcut
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.comDisplay: https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.computers.hoody.comFiles: https://67e89abc123def456789abcd-890abcdef12345678901cdef-files-1.node-us.computers.hoody.comExec: https://67e89abc123def456789abcd-890abcdef12345678901cdef-exec-1.node-us.computers.hoody.comSQLite: https://67e89abc123def456789abcd-890abcdef12345678901cdef-sqlite-1.node-us.computers.hoody.comChoose what the computer includes
Section titled “Choose what the computer includes”These four fields are fixed at creation:
| Field | Default | What it decides |
|---|---|---|
server_id | Required | Where the computer runs. To move it, copy it |
hoody_kit | true; false for an auth token without computers.features.hoody_kit, which gets 403 if it sends true | The Hoody Kit services |
dev_kit | Follows the resolved hoody_kit value | A developer toolchain |
computer_image | debian/13 | The 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.
Set its name, variables and SSH key
Section titled “Set its name, variables and SSH key”These create fields can be changed later with an update:
| Field | Rule |
|---|---|
name | 3-100 letters, digits, hyphens and underscores, unique within the project. Omit it or send "rand" for a generated name |
environment_vars | Seen by new processes once applied in the computer |
ssh_public_key | Omit it and the computer has no SSH access until you set a key with an update |
autostart | true by default: the computer starts when the host machine reboots |
color | A hex color that marks the computer in the Hub’s lists (Colors) |
ssh-keygen -t ed25519 -f ~/.ssh/hoody-computer-1 -N ""Recover a create that timed out
Section titled “Recover a create that timed out”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.
Update a computer
Section titled “Update a computer”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.
hoody computers update "$COMPUTER_ID" --name renamed-computer \ && hoody computers env update --computer "$COMPUTER_ID" --env NODE_ENV=stagingimport { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
await client.api.computers.update(process.env.COMPUTER_ID!, { name: 'renamed-computer', environment_vars: { NODE_ENV: 'staging' }});curl -X PATCH "https://api.hoody.com/api/v1/computers/$COMPUTER_ID" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "renamed-computer", "environment_vars": {"NODE_ENV": "staging"} }'Renames COMPUTER_ID and switches its NODE_ENV to staging in one call.
https://PROJECT_ID-COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/computers/COMPUTER_ID&method=PATCH&bearer_token=HOODY_TOKEN&json={"name":"renamed-computer","environment_vars":{"NODE_ENV":"staging"}}&response=transparentOne request, one link
cURL runs inside your computer and can wrap any HTTP request into a single GET URL. The call stops being something you need a client for and becomes something you can paste into a browser, send in a chat, bookmark, schedule with cron, or drop into a no-code tool.
Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials. It also appears in the cURL service's request log, not only the target's. Prefer a delegated token with minimal permissions and an expiry: see API tokens.
Slashes, colons and braces pass through as they are. The one character you must
encode is an & inside a value, which happens when the wrapped URL
carries its own query string. Left raw it ends the value early, and the rest is
read as cURL's own parameters, so you get a 200 on a request you did
not make.
How the wrapping works Chaining calls into one link Turning a link into a shortcut
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.
Delete a computer
Section titled “Delete a computer”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.
- In the Hub, open Computers, open the computer’s menu and choose Make a copy…, then Make copy.
- Wait until the copy is running and check its contents.
- Open the source computer’s menu, choose Delete…, type the computer’s name to confirm, then choose Delete computer.
set -e
# 1. Copy the computer and wait for the copy (exits 1 if the copy fails)hoody computers copy "$COMPUTER_ID" --target-project "$PROJECT_ID" --name "backup-2025-11-09" --until-doneInspect the copy’s contents and configuration (firewall and network rules are not copied unless you set copy_firewall_rules / copy_network_rules). When you have verified it, delete the source:
# 2. Delete the sourcehoody computers delete "$COMPUTER_ID" -yimport { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });const computerId = process.env.COMPUTER_ID!;
// 1. Copy the computer, then wait until the copy is running; stop if it failed or was left stoppedconst copy = await client.api.computers.copy(computerId, { target_project_id: process.env.PROJECT_ID!, name: 'backup-2025-11-09' });let status = copy.data.status;while (status !== 'running') { if (status === 'failed') throw new Error('Copy failed; the source is kept'); if (status === 'stopped') throw new Error('Copy did not start; check its status and network configuration. The source is kept'); await new Promise((resolve) => setTimeout(resolve, 5000)); status = (await client.api.computers.get(copy.data.id!)).data.status;}Inspect the copy’s contents and configuration (firewall and network rules are not copied unless you set copy_firewall_rules / copy_network_rules). When you have verified it, delete the source:
// 2. Delete the sourceawait client.api.computers.delete(computerId);set -eo pipefail
# 1. Copy the computerCOPY_ID=$(curl -sf -X POST "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/copy" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"target_project_id": "'"$PROJECT_ID"'", "name": "backup-2025-11-09"}' | jq -r '.data.id')
# 2. Wait until the copy is running; stop if it failed or was left stoppedwhile true; do STATUS=$(curl -sf "https://api.hoody.com/api/v1/computers/$COPY_ID" \ -H "Authorization: Bearer $HOODY_TOKEN" | jq -r '.data.status') [ "$STATUS" = running ] && break [ "$STATUS" = failed ] && { echo "Copy failed; the source is kept" >&2; exit 1; } [ "$STATUS" = stopped ] && { echo "Copy did not start; check its status and network configuration. The source is kept" >&2; exit 1; } sleep 5doneInspect the copy’s contents and configuration (firewall and network rules are not copied unless you set copy_firewall_rules / copy_network_rules). When you have verified it, delete the source:
# 3. Delete the sourcecurl -sf -X DELETE "https://api.hoody.com/api/v1/computers/$COMPUTER_ID" \ -H "Authorization: Bearer $HOODY_TOKEN"Copy, then open the check link (COPY_ID is the copy’s data.id) until it shows running; if it shows failed or stopped, keep the source. Inspect the copy’s contents and configuration, and open the delete link only after checking. Delete through a different running computer’s curl-1.
# Copy computerhttps://PROJECT_ID-OTHER_COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/computers/COMPUTER_ID/copy&method=POST&bearer_token=HOODY_TOKEN&json={"target_project_id":"PROJECT_ID","name":"backup-2025-11-09"}&response=transparent
# Check the copyhttps://PROJECT_ID-OTHER_COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/computers/COPY_ID&method=GET&bearer_token=HOODY_TOKEN&response=transparent
# Delete computerhttps://PROJECT_ID-OTHER_COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/computers/COMPUTER_ID&method=DELETE&bearer_token=HOODY_TOKEN&response=transparentOne request, one link
cURL runs inside your computer and can wrap any HTTP request into a single GET URL. The call stops being something you need a client for and becomes something you can paste into a browser, send in a chat, bookmark, schedule with cron, or drop into a no-code tool.
Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials. It also appears in the cURL service's request log, not only the target's. Prefer a delegated token with minimal permissions and an expiry: see API tokens.
Slashes, colons and braces pass through as they are. The one character you must
encode is an & inside a value, which happens when the wrapped URL
carries its own query string. Left raw it ends the value early, and the rest is
read as cURL's own parameters, so you get a 200 on a request you did
not make.
How the wrapping works Chaining calls into one link Turning a link into a shortcut
If a delete is refused, see delete refusals.
Check status and list computers
Section titled “Check status and list computers”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.
hoody computers get "$COMPUTER_ID" --runtime trueimport { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const computer = await client.api.computers.get(process.env.COMPUTER_ID!, { runtime: 'true' });console.log(computer.data.status);curl "https://api.hoody.com/api/v1/computers/$COMPUTER_ID?runtime=true" \ -H "Authorization: Bearer $HOODY_TOKEN"Reads COMPUTER_ID with its runtime information.
https://PROJECT_ID-COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/computers/COMPUTER_ID?runtime=true&method=GET&bearer_token=HOODY_TOKEN&response=transparentOne request, one link
cURL runs inside your computer and can wrap any HTTP request into a single GET URL. The call stops being something you need a client for and becomes something you can paste into a browser, send in a chat, bookmark, schedule with cron, or drop into a no-code tool.
Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials. It also appears in the cURL service's request log, not only the target's. Prefer a delegated token with minimal permissions and an expiry: see API tokens.
Slashes, colons and braces pass through as they are. The one character you must
encode is an & inside a value, which happens when the wrapped URL
carries its own query string. Left raw it ends the value early, and the rest is
read as cURL's own parameters, so you get a 200 on a request you did
not make.
How the wrapping works Chaining calls into one link Turning a link into a shortcut
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.
How many computers can I create?
Section titled “How many computers can I create?”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.
Advanced
Section titled “Advanced”- Realms:
realm_idsseparates 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
ETagfrom aGETinIf-Match. If the current editable settings differ from those the tag represents, the update returns412and 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: trueat create requests/dev/kvmaccess so the computer can run full virtual machines, on a rented dedicated server only. Checkkvmandkvm_notein 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 sendPUT /api/v1/computers/{id}/kvmwith{"kvm": true}while it is stopped. Start it after the request succeeds. See Virtual Machines.
Reference
Section titled “Reference”Fields, states, limits, recipes and troubleshooting: the Create, Edit, Delete reference.
What’s next
Section titled “What’s next”- Managing Computers: start, stop, pause and resume
- Snapshots: back up and restore computer state
- Copy & Sync: duplicate computers across projects and servers
- Projects & Computers: how the two objects relate