# Create, Edit, Delete **Page:** foundation/computers/create-edit-delete [Download Raw Markdown](./foundation/computers/create-edit-delete.md) --- # 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. 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**. ```bash hoody computers create --project "$PROJECT_ID" --server-id "$SERVER_ID" --name dev-environment --hoody-kit ``` ```typescript import { 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); ``` ```bash 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`). The response is the computer, `running` or still `creating`. With `hoody_kit: true` it has a URL for each [Hoody Kit](/kit/) service, generated at once. Wait for `running`, then request the service URL; several services start on their first request: ```json { "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 } } ``` ```text 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 ``` ## 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](/foundation/computers/copy-sync/#cross-server-copy) | | `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](/foundation/computers/create-edit-delete/reference/#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](/foundation/computers/create-edit-delete/reference/#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. A plain computer has no built-in browser shell. Set an `ssh_public_key` for initial SSH access. ## Set its name, variables and SSH key These [create fields](/foundation/computers/create-edit-delete/reference/#create-fields) can be changed later with an [update](#update-a-computer): | 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](/foundation/computers/create-edit-delete/reference/#colors)) | Each computer needs its own SSH public key. Hoody's SSH Proxy routes by public key, so a key reused across computers conflicts. ```bash ssh-keygen -t ed25519 -f ~/.ssh/hoody-computer-1 -N "" ``` ## 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](/foundation/computers/create-edit-delete/reference/#create-retries)). 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 ` in the CLI. Without a key, list the project's computers and look for the name. ## 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. ```bash hoody computers update "$COMPUTER_ID" --name renamed-computer \ && hoody computers env update --computer "$COMPUTER_ID" --env NODE_ENV=staging ``` ```typescript import { 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' } }); ``` ```bash 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. 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](/foundation/computers/create-edit-delete/reference/#update-rules). ## 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](/concepts/realms-projects/#realm-scoped-api-calls) 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 delete is irreversible, and the computer's snapshots are deleted with it. [Copy the computer](/foundation/computers/copy-sync/) or export its data to independent storage first. Before copying, save any `/ramdisk` contents you need to persistent storage. A copy does not include RAM-disk contents or the source's snapshot history. To keep a snapshot's state, [copy from that snapshot](/foundation/computers/copy-sync/#copy-from-a-specific-snapshot) before deleting the source. Copies made earlier keep running as independent computers. 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 ` 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**. ```bash 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-done ``` 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: ```bash # 2. Delete the source hoody computers delete "$COMPUTER_ID" -y ``` ```typescript import { 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 stopped const 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: ```typescript // 2. Delete the source await client.api.computers.delete(computerId); ``` ```bash set -eo pipefail # 1. Copy the computer COPY_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 stopped while 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 5 done ``` 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: ```bash # 3. Delete the source curl -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. If a delete is refused, see [delete refusals](/foundation/computers/create-edit-delete/reference/#delete-refusals). ## 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. ```bash hoody computers get "$COMPUTER_ID" --runtime true ``` ```typescript import { 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); ``` ```bash curl "https://api.hoody.com/api/v1/computers/$COMPUTER_ID?runtime=true" \ -H "Authorization: Bearer $HOODY_TOKEN" ``` Reads COMPUTER_ID with its runtime information. 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](/foundation/computers/create-edit-delete/reference/#lifecycle-states). `hoody computers list` lists all your computers, and `GET /api/v1/projects/{id}/computers` one project's, with [filters](/foundation/computers/create-edit-delete/reference/#list-and-filter). ## 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](/foundation/computers/create-edit-delete/reference/#limits). Computers themselves are not charged; see [Pricing](/foundation/pricing/). ## Advanced - **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](/foundation/hoody-api/realms/#realm-limits). See [realm rules](/foundation/computers/create-edit-delete/reference/#realms). - **Recipes:** create bodies for four kinds of computer and a project-to-computer flow, in [Recipes](/foundation/computers/create-edit-delete/reference/#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](/foundation/hoody-api/authentication/#create-an-automation-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](/api/computers/#update-and-delete-computers). - **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](/foundation/servers/virtual-machines/). ## Reference Fields, states, limits, recipes and troubleshooting: the [Create, Edit, Delete reference](/foundation/computers/create-edit-delete/reference/). ## What's next - [Managing Computers](/foundation/computers/managing/): start, stop, pause and resume - [Snapshots](/foundation/computers/snapshots/): back up and restore computer state - [Copy & Sync](/foundation/computers/copy-sync/): duplicate computers across projects and servers - [Projects & Computers](/foundation/projects-computers/): how the two objects relate