Managing Computers reference
Section titled “Managing Computers reference”Lookup tables for Managing Computers. The Computer Operations API carries the full request and response schemas.
API calls
Section titled “API calls”| Call | What it does | CLI | SDK |
|---|---|---|---|
POST /api/v1/computers/{id}/start | Start stopped computer | hoody computers start | client.api.computers.start |
POST /api/v1/computers/{id}/stop | Gracefully stop computer | hoody computers stop | client.api.computers.stop |
POST /api/v1/computers/{id}/force-stop | Immediately terminate | hoody computers stop --force | client.api.computers.stop(id, undefined, { force: true }) |
POST /api/v1/computers/{id}/restart | Stop then start | hoody computers restart | client.api.computers.restart |
POST /api/v1/computers/{id}/pause | Suspend computer | hoody computers pause | client.api.computers.pause |
POST /api/v1/computers/{id}/resume | Resume suspended computer | hoody computers resume | client.api.computers.resume |
GET /api/v1/computers/{id}/status-logs | View state transition history | hoody computers statushistory list -c with --page, --limit (default 10), --sort-by, --sort-order (default desc) | client.api.computers.listStatusHistory |
GET /api/v1/computers/{id}/stats | Live CPU, memory, disk and network figures | hoody computers stats | client.api.computers.getStats |
GET /api/v1/computers/{id} | Get current computer status | hoody computers get | client.api.computers.get |
An auth token needs computers.actions.start for start and resume, computers.actions.stop for stop, force-stop and pause, computers.actions.restart for restart, and computers.actions.logs for the status log. A project collaborator needs edit permission to run an operation. If the computer’s server belongs to a pool, the collaborator must also be an authorized member of that pool; otherwise the API returns 404. The status log and runtime information are for the project owner only: a collaborator gets a reduced view with no runtime data.
In the Hub, open Computers and open a computer’s actions menu. Depending on your permissions, a running computer offers Stop and Restart, a stopped computer Start, and a paused computer Resume. Expired computers do not offer these actions. To pause or force-stop a computer, use the CLI, SDK or API. You can also test computer operations from your browser:
Manage computer lifecycle - set operation to: start, stop, force-stop, restart, pause, or resume
Path Parameters
Authentication
Use the authentication widget in the header to login or set an API token
Authentication: Authorization: Bearer header (auto-attached for trusted domains)
Custom Headers
Request Body (JSON)
States and operations
Section titled “States and operations”The lifecycle operations move a computer between these states:
startstopped ────────→ running ↑ ↓ │ │ pause │ ↓ │ paused │ ↓ │ │ resume │ ↓ └────── stop ── running| State | Description | Usual next operations |
|---|---|---|
running | Computer is active; services may still be starting | stop, force-stop, restart, pause, delete |
stopped | Computer is halted, no processes running | start, restart, delete |
paused | Computer suspended, state frozen in RAM | resume, stop, force-stop, restart |
creating | Being provisioned (automatic) | None: wait for completion |
failed | Operation failed | delete |
copying | Being duplicated | None: wait for completion |
The API can also report claiming, deleting, and deleted during claim and deletion workflows; every state is on the Create, Edit, Delete reference.
The computer must be in running, stopped, or paused to be managed at all. An operation on a computer already in its target state changes nothing and answers 200: starting or resuming a running computer, stopping or force-stopping a stopped one, pausing a paused one. Restart works from stopped (it starts the computer) and from paused (it resumes, then restarts); resume of a stopped computer starts it. Pausing a stopped computer is refused with 400. Check the current status first with GET /api/v1/computers/{id}: its status field is the current state (running, stopped, paused), and updated_at the last modification time.
| Response | Meaning | What to do |
|---|---|---|
200 “The computer is already running.”, “already stopped.” or “already paused.” in message | The computer was already in the target state; nothing was done | Nothing |
400 “Cannot pause a stopped computer. Start it first.” | Pause sent to a stopped computer | Start it first |
400 “Computer must be in “running”, “stopped”, or “paused” state to be managed” | The computer is in another state, such as creating or failed | Wait for it, or delete a failed computer |
409 COMPUTER_OPERATION_IN_PROGRESS | Another start, stop, setup or maintenance operation is running on this computer; nothing was done | Retry in a few seconds |
409 computer_finalizing “This computer is still being set up. Retry in a few seconds.” | The computer is in claiming; nothing was done | Retry in a few seconds |
504 COMPUTER_HOST_TIMEOUT | The server did not answer in time; the operation may still have completed | Check the computer status before retrying |
What each operation does
Section titled “What each operation does” | Operation | What happens | When to use it |
|---|---|---|
| Start | Computer processes initialize, Hoody Kit services start (if enabled), network connectivity is established, service URLs become accessible | The computer was previously stopped; maintenance or updates have finished; you keep computers stopped when not in use to free the server’s CPU and memory |
| Stop | Requests an orderly shutdown from the computer’s operating system, giving services time to clean up. If shutdown exceeds the deadline, Hoody attempts a forced stop. On success, status changes to stopped | Normal shutdown before updates, maintenance, or resource conservation |
| Force-stop | SIGKILL sent immediately, all processes terminated instantly, no cleanup time given. Can cause data corruption if processes are writing to disk | Graceful stop hangs or times out; emergency situations (runaway process); computer is unresponsive |
| Restart | Graceful stop, wait for stopped state, start | Restart configured services, clear in-memory state, recover from issues, regular maintenance restarts |
| Pause | All computer processes frozen, state saved in RAM, no CPU usage, memory held, service URLs return errors | Temporary suspension during resource constraints, freeze state for debugging, quick pause/resume cycles |
| Resume | Processes continue from their paused in-memory state. Open files remain, but network peers or proxies may have timed out; reconnect affected clients or sessions. Service URLs become accessible again | After a pause |
Stop and restart allow 60 seconds for clean shutdown by default. If shutdown takes longer, the computer may be stopped forcibly; restart then starts it again. To change the clean-shutdown deadline, set timeout in the request body to an integer from 1 to 600 seconds. The whole operation can take longer than that deadline.
Timing
Section titled “Timing”| Operation | Typical duration | What happens |
|---|---|---|
| Start | 5-15 seconds | Boot processes, start services |
| Stop | 5-10 seconds | Graceful shutdown, cleanup |
| Force-stop | <1 second | Immediate kill |
| Restart | 10-25 seconds | Stop + Start: one graceful stop plus one start, back to back |
| Pause | ~1 second | Freeze all processes |
| Resume | 1-2 seconds | Unfreeze, continue execution |
Timing depends on the computer image complexity, the number of running processes, allocated resources, Hoody Kit services (more services means slightly longer) and server load.
Pause or stop
Section titled “Pause or stop”| Pause and resume | Stop and start | |
|---|---|---|
| Speed | Pause about 1 second, resume about 1-2 seconds | Stop about 5-10 seconds, start about 5-15 seconds |
| Processes | All frozen | All terminated |
| RAM state | Preserved; requires RAM for state | Process memory is released. Files in /ramdisk survive stop/start and keep using the server’s RAM until removed or the server reboots |
| Network connections | Socket state retained; connections may time out while paused | Closed |
| Files | Open files preserved | Filesystem preserved |
| Environment | Already-running processes keep the environment they started with; they see updated variables only after they re-exec | Configured services start from a clean runtime state; stop and start does not automatically make systemd services inherit the computer’s environment variables |
| Snapshots | Cannot be created while paused; resume or stop first. Snapshots capture filesystem state only, not RAM | Can create snapshots |
| Best for | Quick suspension | Maintenance, updates; clean state on restart |
Stop and start give a clean runtime state or restart configured services; they are not a general environment-variable propagation mechanism.
Status log
Section titled “Status log”GET /api/v1/computers/{id}/status-logs takes page, limit, sort_by and sort_order.
{ "statusCode": 200, "message": "Status logs retrieved successfully", "data": { "logs": [ { "id": "63f8b0e5c9a1b2d3e4f5a6b7", "computer_id": "890abcdef12345678901cdef", "from_status": "stopped", "to_status": "running", "transition_time": "2025-11-09T14:30:00.000Z", "duration_ms": 12450, "triggered_by": "manual_operation", "metadata": { "kind": "computer_operation", "operation": "start", "actor_user_id": "507f1f77bcf86cd799439022" } }, { "id": "63f8b0e5c9a1b2d3e4f5a6b8", "computer_id": "890abcdef12345678901cdef", "from_status": "running", "to_status": "stopped", "transition_time": "2025-11-09T10:15:00.000Z", "duration_ms": 8320, "triggered_by": "manual_operation", "metadata": null } ], "pagination": { "total": 47, "page": 1, "limit": 10, "totalPages": 5 } }}| Field | What you learn |
|---|---|
from_status, to_status, transition_time | When states changed |
duration_ms | On an operation entry (triggered_by: manual_operation), how long the operation took. On other entries it can be the time since the previous entry instead. null when unknown |
triggered_by | What kind of event triggered the change, such as manual_operation for an operation or computer_creation |
metadata | For an operation, operation names it and actor_user_id identifies the actor when available. For system actions or unavailable or withheld identities, actor_user_id is null; other metadata is retained. Entries without metadata return null |
The log records state changes. Analyze the frequency of restarts (a stability indicator), downtime duration and operation timing patterns.
| Question | Query | Look for |
|---|---|---|
| Did the computer have recent failures? | GET /api/v1/computers/{id}/status-logs?sort_order=desc&limit=20 | Failed states, unexpected stops, slow starts |
| Are startup times slow? | GET /api/v1/computers/{id}/status-logs | duration_ms of “stopped → running” entries with triggered_by: manual_operation; optimize if consistently slow |
| Who stopped the production computer? | GET /api/v1/computers/{prod_id}/status-logs | The triggered_by field, and metadata.actor_user_id on an operation |
For live data, GET /api/v1/computers/{id}?runtime=true adds active terminal sessions, display information and network services with their ports. For program status, PIDs, CPU and memory, run hoody daemon programs status -c "$COMPUTER_ID" --include-stats true. GET /api/v1/computers/{id}/stats (hoody computers stats, client.api.computers.getStats) reports CPU and memory usage for the whole computer.
Autostart
Section titled “Autostart”Autostart controls whether a computer starts by itself when its server boots. Every new computer starts when it is created; autostart: false only keeps it stopped when its server boots. When your server restarts (maintenance, updates, power cycle), all computers with autostart: true start automatically once the server is back online.
| Enable autostart for | Disable autostart for |
|---|---|
| Production services (must be always available) | Development environments (start manually when needed) |
| Critical infrastructure (databases, APIs) | Testing computers (ephemeral) |
| Monitoring computers (must run continuously) | Resource-intensive computers (start on-demand) |
| Automation computers (CI/CD, cron jobs) | Temporary/experimental computers |
Questions
Section titled “Questions”| Question | Answer |
|---|---|
| What happens to service URLs when a computer is stopped? | Services running inside the computer are unavailable while it is stopped; an allowed request may receive 503 COMPUTER_STOPPED. The URLs remain valid and work again after the services start. Proxy log URLs can still be read, subject to their access permissions and availability |
| Can I be notified when operations complete? | The response arrives when the operation is done, with the new status and an operation_id; the outcome is also a computer.operation.completed or computer.operation.failed event with that operation_id, listed by GET /api/v1/events with computer_id and event_type. After a 504, poll the computer status or status-logs endpoints. To get an alert, have the script that polls call POST /api/v1/notifications/notify on a hoody-notifications server when it sees the operation finish; the service sends what it is asked to send and does not watch computer operations itself |
| Can computers auto-restart if they crash? | Not automatically via the API. Implement monitoring that checks status and restarts if needed, or use systemd inside computers for process-level auto-restart, or configure autostart: true for server boot recovery |
| Can I start many computers at once? | Yes. Operations are independent HTTP requests, so you can run them in parallel within the per-user rate limit; past it the API answers 429, and a bulk script retries after Retry-After (example) |
Recipes
Section titled “Recipes”Stop idle computers by name
Section titled “Stop idle computers by name”Stop computers when not in use. Automate with cron: schedule stops at 6 PM, starts at 8 AM.
// Stop non-critical computers during off-hours.// The list endpoint is paginated (50 computers per page, 100 max), so page through it, then filter client-side by name.async function checkedFetch(url, options) { const r = await fetch(url, options); if (!r.ok) throw new Error(r.status + ' ' + await r.text()); return r;}
const nonCritical = ['staging-api', 'test-db', 'dev-frontend'];
const all = [];for (let page = 1; ; page++) { const { data } = await checkedFetch( `https://api.hoody.com/api/v1/computers?page=${page}&limit=100`, { headers: { Authorization: `Bearer ${process.env.HOODY_TOKEN}` } } ).then(r => r.json()); all.push(...data.computers); if (page >= data.pagination.totalPages) break;}
const targets = all.filter( c => nonCritical.includes(c.name) && c.status === 'running');
for (const c of targets) { await checkedFetch( `https://api.hoody.com/api/v1/computers/${c.id}/stop`, { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.HOODY_TOKEN}` } } );}Start a project’s stopped computers
Section titled “Start a project’s stopped computers”async function checkedFetch(url, options) { const r = await fetch(url, options); if (!r.ok) throw new Error(r.status + ' ' + await r.text()); return r;}
const projectId = process.env.HOODY_PROJECT_ID; // the id from GET /api/v1/projects
// Get all computers in projectconst computers = [];for (let page = 1; ; page++) { const { data } = await checkedFetch( `https://api.hoody.com/api/v1/projects/${projectId}/computers?page=${page}&limit=100`, { headers: { Authorization: `Bearer ${process.env.HOODY_TOKEN}` } } ).then(r => r.json()); computers.push(...data.computers); if (page >= data.pagination.totalPages) break;}
// Start all stopped computersfor (const computer of computers) { if (computer.status === 'stopped') { await checkedFetch( `https://api.hoody.com/api/v1/computers/${computer.id}/start`, { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.HOODY_TOKEN}` } } ); console.log(`Started: ${computer.name}`); }}Stop every paused computer
Section titled “Stop every paused computer”Stopping frees the RAM a paused computer holds.
// Stop all paused computers (free up RAM).// The list endpoint takes no status filter; filter client-side on the returned array.async function checkedFetch(url, options) { const r = await fetch(url, options); if (!r.ok) throw new Error(r.status + ' ' + await r.text()); return r;}
const computers = [];for (let page = 1; ; page++) { const { data } = await checkedFetch( `https://api.hoody.com/api/v1/computers?page=${page}&limit=100`, { headers: { Authorization: `Bearer ${process.env.HOODY_TOKEN}` } } ).then(r => r.json()); computers.push(...data.computers); if (page >= data.pagination.totalPages) break;}
const paused = computers.filter(c => c.status === 'paused');
for (const computer of paused) { await checkedFetch( `https://api.hoody.com/api/v1/computers/${computer.id}/stop`, { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.HOODY_TOKEN}` } } );}Restart several computers at once
Section titled “Restart several computers at once”Restart multiple computers simultaneously. Each request is checked, a 429 is retried after Retry-After, and the script reports success only when every request succeeded:
const computerIds = [ '890abcdef12345678901cdef', '901bcdef12345678901cdefa', '012cdef123456789abcdef01'];
async function computerAction(id, action) { for (let attempt = 0; attempt < 5; attempt++) { const response = await fetch(`https://api.hoody.com/api/v1/computers/${id}/${action}`, { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.HOODY_TOKEN}` } }); if (response.ok) return; if (response.status !== 429) { throw new Error(`${action} ${id}: ${response.status} ${await response.text()}`); } const waitSeconds = Number(response.headers.get('Retry-After')) || 60; await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000)); } throw new Error(`${action} ${id}: still rate limited`);}
// Restart all in parallelconst results = await Promise.allSettled(computerIds.map(id => computerAction(id, 'restart')));const failed = results.filter(r => r.status === 'rejected');if (failed.length) { failed.forEach(r => console.error(r.reason.message)); process.exit(1);}console.log('All computers restarted');Starting works the same way:
await Promise.all(computerIds.map(id => computerAction(id, 'start')));Deploy new code
Section titled “Deploy new code”Snapshot, deploy, restart for a clean state, then check the services. Stop if snapshot creation fails or does not return a snapshot name. Record that name before deploying. If deployment fails: restore the snapshot to roll back (Snapshots); a restore replaces the computer’s filesystem with the snapshot’s; data in /ramdisk and data mounted from other computers is not rolled back.
set -eo pipefail
# 1. Snapshot current state (safety)hoody snapshots create -c "$COMPUTER_ID" --alias "pre-deploy-2025-11-09"read -r -p "Note the snapshot name above. Press Enter to deploy, Ctrl-C if no name was returned. "
# 2. Access terminal to deploy, then deploy code
# 3. Restart computer for clean statehoody computers restart "$COMPUTER_ID"
# 4. Verify services are runninghoody computers get "$COMPUTER_ID" --runtime true// 1. Snapshot current state (safety)const snapshot = await client.api.snapshots.create(COMPUTER_ID, { alias: 'pre-deploy-2025-11-09'});const snapshotName = snapshot.data?.snapshot?.name;if (!snapshotName) throw new Error('Snapshot returned no name: stop here');console.log(`Rollback snapshot: ${snapshotName}`);
// 2. Deploy code via terminal...
// 3. Restart computer for clean stateawait client.api.computers.restart(COMPUTER_ID);
// 4. Verify services are runningconst status = await client.api.computers.get(COMPUTER_ID, { runtime: 'true' });console.log(status.data);set -eo pipefail
# 1. Snapshot current state (safety); stop unless it returns a nameSNAPSHOT_NAME=$(curl --fail-with-body -sS -X POST "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/snapshots" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"alias": "pre-deploy-2025-11-09"}' | jq -er '.data.snapshot.name')echo "Rollback snapshot: $SNAPSHOT_NAME"
# 2. Access terminal to deploy# https://$PROJECT_ID-$COMPUTER_ID-terminal-1.$SERVER.computers.hoody.com
# 3. Restart computer for clean statecurl --fail-with-body -sS -X POST "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/restart" \ -H "Authorization: Bearer $HOODY_TOKEN"
# 4. Verify services are runningcurl --fail-with-body -sS "https://api.hoody.com/api/v1/computers/$COMPUTER_ID?runtime=true" \ -H "Authorization: Bearer $HOODY_TOKEN"Three links for the deploy sequence: snapshot, restart, then check runtime status. Route them through a different running computer’s curl-1. The restart briefly takes down the very service that would carry this request.
# Snapshothttps://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/snapshots&method=POST&bearer_token=HOODY_TOKEN&json={"alias":"pre-deploy-2025-11-09"}&response=transparent
# Restarthttps://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/restart&method=POST&bearer_token=HOODY_TOKEN&response=transparent
# Check runtime statushttps://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?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
Run maintenance from a script
Section titled “Run maintenance from a script”Run it at 2 AM via cron. waitForStatus is the helper in Wait until an operation finishes. environment_vars replaces the entire map. Include every variable you want to keep; omitted variables are removed.
// Automated maintenance scriptasync function performMaintenance(computerId) { const token = process.env.HOODY_TOKEN; const headers = { 'Authorization': `Bearer ${token}` }; const base = `https://api.hoody.com/api/v1/computers/${computerId}`;
// Throws on any error response, so a failed step stops the script async function call(url, options = {}) { const response = await fetch(url, { ...options, headers: { ...headers, ...options.headers } }); if (!response.ok) { throw new Error(`${options.method || 'GET'} ${url} failed: ${response.status} ${await response.text()}`); } return response.json(); }
// 1. Stop computer await call(`${base}/stop`, { method: 'POST' });
// 2. Wait for stopped await waitForStatus(computerId, 'stopped');
// 3. Update resources await call(base, { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ environment_vars: { "UPDATED": "true" } }) });
// 4. Restart await call(`${base}/start`, { method: 'POST' });
// 5. Verify running await waitForStatus(computerId, 'running'); const status = await call(base);
return status.data.status === 'running';}
// Run at 2 AM via cronperformMaintenance('890abcdef12345678901cdef');Switch traffic blue to green
Section titled “Switch traffic blue to green”Start the green computer, check that your app on it is healthy, re-point the alias, monitor green in production, and only then stop blue. A running status only says the computer is up, not that your app works, so the scripts pause for you at both checks. An alias’s computer_id is immutable, so re-pointing means delete and recreate; the alias is gone between those two calls, and a change reaches the alias URL in about 30 seconds, sometimes longer (Aliases).
Configure and test green’s proxy permissions before you change the alias. Blue’s computer-specific access rules do not transfer to green. Check that both anonymous and authenticated requests get the access you intend.
To keep the existing alias URL, check that blue and green return the same non-null server_name from GET /api/v1/computers/{id}. If they differ, the recreated alias has a different hostname. Update your clients, or configure and verify your custom-domain route to the new target, before you stop blue.
Read the existing alias first (GET /api/v1/proxy/aliases/{id}) and note its alias, program, index (for an http or https alias this is the port), target_path and allow_path_override. Use those values in the create step; only computer_id changes to green. The scripts below write them as ALIAS_NAME, PROGRAM, PORT (the index value) and TARGET_PATH. For a built-in program, send index instead of port; if allow_path_override was false, send that as well. The recreated alias is enabled and never expires: if the old one had an expires_at or was disabled, send expires_at (--expires-at) or enabled: false (--no-enabled) too.
The recreated alias also belongs to the realms green is in when you create it, not to the old alias’s realms. If you use realms, check that green’s realm_ids (from GET /api/v1/computers/{id}) include every realm that lists the old alias (GET /api/v1/proxy/aliases?realm_id=...) before you delete it.
set -eo pipefail
# 1. Start green computerhoody computers start "$GREEN_ID"
# 2. Check green is running, then check your app's own health endpointhoody computers get "$GREEN_ID" --runtime trueread -r -p "Is the app on green healthy? Press Enter to switch the alias, Ctrl-C to stop. "
# 3. Re-point alias to green (delete + recreate; computer_id is immutable)hoody proxy aliases delete "$ALIAS_ID" -yhoody proxy aliases create --computer-id "$GREEN_ID" \ --alias "$ALIAS_NAME" --program "$PROGRAM" --port "$PORT" --target-path "$TARGET_PATH"
# 4. Check the alias reaches green and monitor productionread -r -p "Is production healthy on green? Press Enter to stop blue, Ctrl-C to keep it. "
# 5. After verification, stop bluehoody computers stop "$BLUE_ID"import { createInterface } from 'node:readline/promises';const rl = createInterface({ input: process.stdin, output: process.stdout });
// 1. Start green computerawait client.api.computers.start(GREEN_ID);
// 2. Verify green is healthyconst green = await client.api.computers.get(GREEN_ID, { runtime: 'true' });console.log(green.data.status); // 'running'// 'running' says the computer is up, not that your app works:// check your app's own health endpoint before you go onawait rl.question('Is the app on green healthy? Press Enter to switch the alias, Ctrl-C to stop. ');
// 3. Re-point alias to green (delete + recreate; computer_id is immutable)await client.api.proxy.aliases.delete(ALIAS_ID);await client.api.proxy.aliases.create({ computer_id: GREEN_ID, alias: ALIAS_NAME, program: PROGRAM, port: PORT, target_path: TARGET_PATH});
// 4. Check the alias reaches green and monitor productionawait rl.question('Is production healthy on green? Press Enter to stop blue, Ctrl-C to keep it. ');rl.close();
// 5. After verification, stop blueawait client.api.computers.stop(BLUE_ID);set -eo pipefail
# 1. Start green computercurl --fail-with-body -sS -X POST "https://api.hoody.com/api/v1/computers/$GREEN_ID/start" \ -H "Authorization: Bearer $HOODY_TOKEN"
# 2. Check green is running, then check your app's own health endpointcurl --fail-with-body -sS "https://api.hoody.com/api/v1/computers/$GREEN_ID?runtime=true" \ -H "Authorization: Bearer $HOODY_TOKEN"read -r -p "Is the app on green healthy? Press Enter to switch the alias, Ctrl-C to stop. "
# 3. Re-point alias to green (delete + recreate; computer_id is immutable)curl --fail-with-body -sS -X DELETE "https://api.hoody.com/api/v1/proxy/aliases/$ALIAS_ID" \ -H "Authorization: Bearer $HOODY_TOKEN"
curl --fail-with-body -sS -X POST "https://api.hoody.com/api/v1/proxy/aliases" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "computer_id": "'"$GREEN_ID"'", "alias": "'"$ALIAS_NAME"'", "program": "'"$PROGRAM"'", "port": '"$PORT"', "target_path": "'"$TARGET_PATH"'" }'
# 4. Check the alias reaches green and monitor productionread -r -p "Is production healthy on green? Press Enter to stop blue, Ctrl-C to keep it. "
# 5. After verification, stop bluecurl --fail-with-body -sS -X POST "https://api.hoody.com/api/v1/computers/$BLUE_ID/stop" \ -H "Authorization: Bearer $HOODY_TOKEN"Links for the cutover: start green, check it is running and your app is healthy, swap the alias, check production on green, then stop blue. Route them through a third running computer’s curl-1: green isn’t up yet for the first call, and blue is stopped by the last one.
# Start greenhttps://PROJECT_ID-OTHER_COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/computers/GREEN_ID/start&method=POST&bearer_token=HOODY_TOKEN&response=transparent
# Check green is runninghttps://PROJECT_ID-OTHER_COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/computers/GREEN_ID?runtime=true&method=GET&bearer_token=HOODY_TOKEN&response=transparent
# Delete aliashttps://PROJECT_ID-OTHER_COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/proxy/aliases/ALIAS_ID&method=DELETE&bearer_token=HOODY_TOKEN&response=transparent
# Create aliashttps://PROJECT_ID-OTHER_COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/proxy/aliases&method=POST&bearer_token=HOODY_TOKEN&json={"computer_id":"GREEN_ID","alias":"ALIAS_NAME","program":"PROGRAM","port":"PORT","target_path":"TARGET_PATH"}&response=transparent
# Stop bluehttps://PROJECT_ID-OTHER_COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/computers/BLUE_ID/stop&method=POST&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
Wait until an operation finishes
Section titled “Wait until an operation finishes”The response normally arrives once the operation is done. After a 504 the outcome is unknown: don’t assume success, poll until the computer reaches the state you asked for.
// Don't assume success - verifyconst token = process.env.HOODY_TOKEN;
async function checkedFetch(url, options) { const r = await fetch(url, options); if (!r.ok) throw new Error(r.status + ' ' + await r.text()); return r;}
// Poll until the computer reaches the statusasync function waitForStatus(id, status) { let attempts = 0; while (attempts < 30) { const res = await checkedFetch( `https://api.hoody.com/api/v1/computers/${id}`, { headers: { 'Authorization': `Bearer ${token}` }} ).then(r => r.json());
if (res.data.status === status) { return true; }
await new Promise(r => setTimeout(r, 1000)); attempts++; }
throw new Error(`Computer did not reach ${status} in time`);}
async function stopComputer(id) { const r = await fetch(`https://api.hoody.com/api/v1/computers/${id}/stop`, { method: 'POST', headers: { 'Authorization': `Bearer ${token}` } }); // A 504 means the outcome is unknown: poll. Any other error is a failure. if (!r.ok && r.status !== 504) { throw new Error(r.status + ' ' + await r.text()); }
return waitForStatus(id, 'stopped');}Practices
Section titled “Practices”| Practice | How |
|---|---|
| Snapshot before risky operations | Before forcing a stop or major changes: POST /api/v1/computers/{id}/snapshots with {"alias": "before-maintenance"} |
| Prefer graceful stop to force-stop | POST /api/v1/computers/{id}/stop is preferred: it gives processes time to clean up. POST /api/v1/computers/{id}/force-stop is a last resort only: it can corrupt data |
| Document operation triggers | The API has no comment field on operations, so record the reason elsewhere, such as a comment in your automation script: // Stopping computer for scheduled backup - see RUNBOOK.md section 4.2 before await stopComputer(prodId); |
| Coordinate on shared computers | Notify the team via chat or email, check who’s connected, and schedule during off-hours when possible. See Multiplayer by Default for collaboration context |
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | What to do |
|---|---|---|
| Graceful stop hangs: the stop operation doesn’t complete | The computer’s shutdown or its cleanup has not completed | Check the computer’s status and wait for the earlier operation to finish (a second operation returns 409 COMPUTER_OPERATION_IN_PROGRESS). If the stop failed and the computer is still running, force stop (POST /api/v1/computers/{id}/force-stop) if necessary, and check what’s running: SSH or terminal into the computer, run ps aux and identify stuck processes |
| A resumed computer has lost its sessions and in-memory state | Its server rebooted while it was paused. A reboot loses the paused state: the computer comes back stopped, or running if autostart is on, and a resume starts a stopped one | Reopen your sessions and restart what was running |
A valid operation returns 400 | Pause sent to a stopped computer, the computer is not running, stopped or paused, or a start, resume or restart of a computer whose network policy could not be applied | Read the response message. If it says no network policy is in force, configure the computer’s network before retrying. Otherwise see States and operations |
| Start fails or the computer is stuck in “creating” | See below | A computer will not start |
| Status shows “running” but service URLs fail | See below | Service URLs fail after a start |
| The computer restarts unexpectedly | See below | A computer restarts unexpectedly |
A computer will not start
Section titled “A computer will not start”Start operation fails or computer stuck in “creating”:
-
Check status logs:
Terminal window GET /api/v1/computers/{id}/status-logs?limit=5&sort_order=desc# Look for failed states; why a computer failed is failure_reason on GET /api/v1/computers/{id} -
Check live server runtime: this endpoint needs a signed-in session JWT and the base API URL. Auth tokens and HTTP Basic credentials get
403, and realm-scoped requests are not supported.Terminal window GET /api/v1/servers/{rental_id}/runtime# {rental_id} is the rental id (the same id GET /api/v1/servers/{id} takes), not data.server_id.# A 200 response with data.stale == false indicates a live probe; for a subserver slice, also check that data.health == "ok".# A 503 RUNTIME_UNAVAILABLE response means live runtime information could not be collected. -
Check resource availability: the server may be at capacity. Check its available resources and computer limit; delete computers you no longer need or copy this computer to a server with capacity.
-
Look for image issues (Images):
Terminal window GET /api/v1/computers/{id}# Check computer_image is valid
Service URLs fail after a start
Section titled “Service URLs fail after a start”Computer status shows “running” but service URLs fail:
-
Wait for services to initialize: status changes to “running” before all services are ready. Wait 30-60 seconds after start.
-
Check program status: run
hoody daemon programs status -c "$COMPUTER_ID"and verify that the Terminal and Display program entries are running. -
Verify hoody_kit is enabled:
Terminal window GET /api/v1/computers/{id}# Check: "hoody_kit": true -
Check specific service: inspect the Terminal and Display program entries.
Terminal window hoody daemon programs status -c "$COMPUTER_ID"
A computer restarts unexpectedly
Section titled “A computer restarts unexpectedly”-
Autostart enabled + server rebooted:
Terminal window GET /api/v1/computers/{id}# Check: "autostart": true -
Check status logs for pattern:
Terminal window GET /api/v1/computers/{id}/status-logs?limit=20# Look for frequent "stopped → running" transitions# Check triggered_by field -
Process-level crashes: a crashed process restarts only if its supervisor is set to restart it. Check its systemd unit or, for a Hoody Daemon program, its
autorestartsetting. Check logs inside the computer. Or have a monitoring script that detects the crash callPOST /api/v1/notifications/notifyon hoody-notifications; the service does not detect crashes on its own, and a monitor for a stopped computer has to run outside it.