# Managing Computers reference **Page:** foundation/computers/managing/reference [Download Raw Markdown](./foundation/computers/managing/reference.md) --- # Managing Computers reference Lookup tables for [Managing Computers](/foundation/computers/managing/). The [Computer Operations API](/api/computer-operations/) carries the full request and response schemas. ## 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}`](/api/computers/) | 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: ## States and operations The lifecycle operations move a computer between these states: ``` start stopped ────────→ 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](/foundation/computers/create-edit-delete/reference/#lifecycle-states) 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 | 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 | 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 | | 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 `GET /api/v1/computers/{id}/status-logs` takes `page`, `limit`, `sort_by` and `sort_order`. ```json { "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 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 | 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`](/api/notifications/#event-history) 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](/kit/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](#restart-several-computers-at-once)) | ## Recipes ### Stop idle computers by name Stop computers when not in use. **Automate with cron:** schedule stops at 6 PM, starts at 8 AM. ```javascript // 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 ```javascript 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 project const 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 computers for (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 Stopping frees the RAM a paused computer holds. ```javascript // 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 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: ```javascript 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 parallel const 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: ```javascript await Promise.all(computerIds.map(id => computerAction(id, 'start'))); ``` ### 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](/foundation/computers/snapshots/#restore-a-snapshot)); a restore replaces the computer's filesystem with the snapshot's; data in `/ramdisk` and data mounted from other computers is not rolled back. ```bash 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 state hoody computers restart "$COMPUTER_ID" # 4. Verify services are running hoody computers get "$COMPUTER_ID" --runtime true ``` ```typescript // 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 state await client.api.computers.restart(COMPUTER_ID); // 4. Verify services are running const status = await client.api.computers.get(COMPUTER_ID, { runtime: 'true' }); console.log(status.data); ``` ```bash set -eo pipefail # 1. Snapshot current state (safety); stop unless it returns a name SNAPSHOT_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 state curl --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 running curl --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. ### Run maintenance from a script Run it at 2 AM via cron. `waitForStatus` is the helper in [Wait until an operation finishes](#wait-until-an-operation-finishes). `environment_vars` replaces the entire map. Include every variable you want to keep; omitted variables are removed. ```javascript // Automated maintenance script async 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 cron performMaintenance('890abcdef12345678901cdef'); ``` ### 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](/foundation/proxy/aliases/)). Configure and test green's [proxy permissions](/foundation/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. ```bash set -eo pipefail # 1. Start green computer hoody computers start "$GREEN_ID" # 2. Check green is running, then check your app's own health endpoint hoody computers get "$GREEN_ID" --runtime true 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) hoody proxy aliases delete "$ALIAS_ID" -y hoody 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 production read -r -p "Is production healthy on green? Press Enter to stop blue, Ctrl-C to keep it. " # 5. After verification, stop blue hoody computers stop "$BLUE_ID" ``` ```typescript import { createInterface } from 'node:readline/promises'; const rl = createInterface({ input: process.stdin, output: process.stdout }); // 1. Start green computer await client.api.computers.start(GREEN_ID); // 2. Verify green is healthy const 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 on await 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 production await rl.question('Is production healthy on green? Press Enter to stop blue, Ctrl-C to keep it. '); rl.close(); // 5. After verification, stop blue await client.api.computers.stop(BLUE_ID); ``` ```bash set -eo pipefail # 1. Start green computer curl --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 endpoint curl --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 production read -r -p "Is production healthy on green? Press Enter to stop blue, Ctrl-C to keep it. " # 5. After verification, stop blue curl --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. ### 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. ```javascript // Don't assume success - verify const 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 status async 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 | 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](/vision/multiplayer/) for collaboration context | ## 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](#states-and-operations) | | Start fails or the computer is stuck in "creating" | See below | [A computer will not start](#a-computer-will-not-start) | | Status shows "running" but service URLs fail | See below | [Service URLs fail after a start](#service-urls-fail-after-a-start) | | The computer restarts unexpectedly | See below | [A computer restarts unexpectedly](#a-computer-restarts-unexpectedly) | ### A computer will not start Start operation fails or computer stuck in "creating": 1. **Check status logs:** ```bash 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} ``` 2. **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. ```bash 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. ``` 3. **Check resource availability:** the server may be at capacity. Check its available resources and computer limit; delete computers you no longer need or [copy](/foundation/computers/copy-sync/#cross-server-copy) this computer to a server with capacity. 4. **Look for image issues** ([Images](/foundation/computers/images/)): ```bash GET /api/v1/computers/{id} # Check computer_image is valid ``` ### Service URLs fail after a start Computer status shows "running" but service URLs fail: 1. **Wait for services to initialize:** status changes to "running" before all services are ready. Wait 30-60 seconds after start. 2. **Check program status:** run `hoody daemon programs status -c "$COMPUTER_ID"` and verify that the Terminal and Display program entries are running. 3. **Verify hoody_kit is enabled:** ```bash GET /api/v1/computers/{id} # Check: "hoody_kit": true ``` 4. **Check specific service:** inspect the Terminal and Display program entries. ```bash hoody daemon programs status -c "$COMPUTER_ID" ``` ### A computer restarts unexpectedly 1. **Autostart enabled + server rebooted:** ```bash GET /api/v1/computers/{id} # Check: "autostart": true ``` 2. **Check status logs for pattern:** ```bash GET /api/v1/computers/{id}/status-logs?limit=20 # Look for frequent "stopped → running" transitions # Check triggered_by field ``` 3. **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](/kit/daemons/) program, its `autorestart` setting. Check logs inside the computer. Or have a monitoring script that detects the crash call `POST /api/v1/notifications/notify` on [hoody-notifications](/kit/notifications/); the service does not detect crashes on its own, and a monitor for a stopped computer has to run outside it.