# Managing Computers **Page:** foundation/computers/managing [Download Raw Markdown](./foundation/computers/managing.md) --- # Managing Computers A computer moves between states through HTTP endpoints: start, stop, force-stop, restart, pause, and resume. Every transition is recorded in a status log you can read back. This page assumes you have [created a computer](/foundation/computers/create-edit-delete/). Stop, force-stop, restart and pause interrupt everything running in that computer, terminal sessions and Hoody Kit programs included. Try them on a computer you can spare. Start a computer in the morning and pause it in the evening: ```bash # Morning: Start your dev computer hoody computers start "$DEV_ID" # Work all day via computer URLs # https://$PROJECT_ID-$DEV_ID-terminal-1.$SERVER.computers.hoody.com # https://$PROJECT_ID-$DEV_ID-display-1.$SERVER.computers.hoody.com # Evening: Pause (resumes in seconds tomorrow) hoody computers pause "$DEV_ID" ``` ```typescript // Morning: Start your dev computer await client.api.computers.start(DEV_ID); // Work all day via computer URLs... // Evening: Pause (resumes in seconds tomorrow) await client.api.computers.pause(DEV_ID); ``` ```bash # Morning: Start your dev computer curl -X POST "https://api.hoody.com/api/v1/computers/$DEV_ID/start" \ -H "Authorization: Bearer $HOODY_TOKEN" # Work all day via computer URLs # https://$PROJECT_ID-$DEV_ID-terminal-1.$SERVER.computers.hoody.com # https://$PROJECT_ID-$DEV_ID-display-1.$SERVER.computers.hoody.com # Evening: Pause (resumes in seconds tomorrow) curl -X POST "https://api.hoody.com/api/v1/computers/$DEV_ID/pause" \ -H "Authorization: Bearer $HOODY_TOKEN" ``` Morning start, evening pause. Route them through a different running computer's curl-1: DEV_ID is stopped when the morning link runs, and can't serve the request that starts it. Pause rather than stop: resume takes one to two seconds, and terminal sessions, open editors and in-memory state survive. The usual next operations per state: | State | Usual next operations | |---|---| | `running` | stop, force-stop, restart, pause, delete | | `stopped` | start, restart, delete | | `paused` | resume, stop, force-stop, restart | Repeating start, stop, force-stop, pause or resume changes nothing and answers `200` with "already running", "already stopped" or "already paused" in `message`. Pausing a stopped computer returns `400`. Operations need a `running`, `stopped` or `paused` computer; other [states](/foundation/computers/managing/reference/#states-and-operations) generally return `400`. A computer in `claiming` returns `409` while setup finishes. For a non-admin user, an expired computer returns `409 COMPUTER_EXPIRED`; start, resume and restart can instead return `403` when its owner no longer has access to its server. In the Hub, open **Computers**, then open a computer's actions menu, or select the computer and open its menu. Choose **Start**, **Stop**, **Restart** or **Resume**. Which ones appear depends on the computer's state: a running computer offers **Restart** and **Stop**, a stopped one **Start**, a paused one **Resume**. Stop and Restart ask you to confirm. To pause or force-stop a computer, use the CLI, SDK or API. ## Start a computer The response carries the computer's new `status`: ```json { "statusCode": 200, "message": "Computer started.", "data": { "error": false, "operation": "start", "computer_id": "890abcdef12345678901cdef", "project_id": "012cdef123456789abcdef01", "message": "Computer started.", "status": "running" } } ``` Start usually completes in seconds; heavier computers take longer. The status turns `running` before every service is ready, so wait 30 to 60 seconds before calling service URLs. `GET /api/v1/computers/{id}` returns the current `status`. A computer starts by itself when it is created, and when its server boots if `autostart` is on (the default). A restore leaves a stopped computer stopped. ## Stop a computer A graceful stop asks the computer's operating system to shut down normally and gives its services time to clean up. If shutdown runs past the deadline, Hoody attempts a forced stop. Force-stop ends the computer without waiting for a clean shutdown. Stopping ends every connection: terminal sessions close, displays disconnect, in-flight file operations fail. On a shared computer, tell the team first and check `runtime_info.displays[].connected_clients` and `runtime_info.terminals` from `GET /api/v1/computers/{id}?runtime=true`. Only the project owner sees this data, so a collaborator asks the owner. **Force-stop can cause data corruption** if processes are writing to disk. Use only when graceful stop hangs or in emergency situations. Stop gracefully first. Run each step on its own and check its result. If the client times out, check the computer's status before you go on. While an earlier operation is still running, another one returns `409 COMPUTER_OPERATION_IN_PROGRESS`: wait for it to finish. Force-stop only if the stop failed and the computer is still running. Once it is stopped, start it: ```bash # If the computer is unresponsive, try a graceful stop first hoody computers stop "$COMPUTER_ID" # Only if the stop failed and the computer is still running hoody computers stop "$COMPUTER_ID" --force # Once the computer is stopped, start it hoody computers start "$COMPUTER_ID" ``` ```typescript // Try graceful stop first await client.api.computers.stop(COMPUTER_ID); // Only if the stop failed and the computer is still running await client.api.computers.stop(COMPUTER_ID, undefined, { force: true }); // Once the computer is stopped, start it await client.api.computers.start(COMPUTER_ID); ``` ```bash # If the computer is unresponsive, try a graceful stop first curl -X POST "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/stop" \ -H "Authorization: Bearer $HOODY_TOKEN" # Only if the stop failed and the computer is still running curl -X POST "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/force-stop" \ -H "Authorization: Bearer $HOODY_TOKEN" # Once the computer is stopped, start it curl -X POST "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/start" \ -H "Authorization: Bearer $HOODY_TOKEN" ``` Graceful stop first. Force-stop only if the stop failed and the computer is still running, then start it once it is stopped. Route them through a different running computer's curl-1: an unresponsive or stopped one can't serve them. ## Restart a computer `restart` is a graceful stop, a wait for the stopped state, then a start: the same time and result as stop then start, in one request. Use it to restart configured services or clear in-memory state. ## Pause and resume Pause freezes every process with its state in RAM; resume continues exactly where it paused. | | Pause and resume | Stop and start | |---|---|---| | Processes | Frozen, then continue | Terminated | | RAM state and open files | Preserved | Lost or closed; the filesystem is preserved | | Network connections | Can time out while paused; reconnect after resuming | Closed | | Snapshots | Not while paused: resume or stop first | Allowed | | Best for | Quick suspension | Maintenance, updates | A paused computer uses no CPU, but keeps its RAM and disk usage and still counts toward any computer-count limit. Its service URLs return errors until resumed. A server reboot loses the paused state: start the computer instead. ## Do changes need a restart? Usually not. After a successful live sync, new exec and console processes see changed environment variables at once, and [`computers env`](/api/computer-env/) writes also update `/etc/environment`, so new SSH and console logins see them. Running processes see them only after they re-exec; systemd services do not inherit them, even after a stop and start. In the Hub, open **Computers**, select the computer, and on **Overview** find **Environment variables**. Choose **Edit variables**, add or change the variables, then choose **Save**. With `PATCH /api/v1/computers/{id}` you can request updates to the name, autostart, environment variables and SSH key while the computer is running, paused or stopped. Access and other update rules still apply; updates are refused while it is claiming or quarantined, or when its server no longer permits changes. See [Update rules](/foundation/computers/create-edit-delete/reference/#update-rules). Narrowing `ramdisk_scope` is rejected while running. Stop first only when configured services must restart; then stop, update, start. `environment_vars` replaces the entire map. Include every variable you want to keep; omitted variables are removed. The CLI's `hoody computers env update` changes only the variables you pass; the others keep their values. ```bash # 1. Stop computer gracefully hoody computers stop "$PROD_ID" # 2. Update configuration hoody computers env update --computer "$PROD_ID" --env CONFIG_VERSION=2.0 # 3. Restart with new config hoody computers start "$PROD_ID" ``` ```typescript // 1. Stop computer gracefully await client.api.computers.stop(PROD_ID); // 2. Update configuration await client.api.computers.update(PROD_ID, { environment_vars: { CONFIG_VERSION: '2.0' } }); // 3. Restart with new config await client.api.computers.start(PROD_ID); ``` ```bash # 1. Stop computer gracefully curl -X POST "https://api.hoody.com/api/v1/computers/$PROD_ID/stop" \ -H "Authorization: Bearer $HOODY_TOKEN" # 2. Update configuration curl -X PATCH "https://api.hoody.com/api/v1/computers/$PROD_ID" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"environment_vars": {"CONFIG_VERSION": "2.0"}}' # 3. Restart with new config curl -X POST "https://api.hoody.com/api/v1/computers/$PROD_ID/start" \ -H "Authorization: Bearer $HOODY_TOKEN" ``` Stop, update, start. Route them through a different running computer's curl-1: PROD_ID is stopped partway through. ## Start computers when the server boots ```bash # Enable autostart hoody computers update "$COMPUTER_ID" --autostart ``` ```typescript // Enable autostart await client.api.computers.update(COMPUTER_ID, { autostart: true }); ``` ```bash # Enable autostart curl -X PATCH "https://api.hoody.com/api/v1/computers/$COMPUTER_ID" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"autostart": true}' ``` Flips COMPUTER_ID's autostart flag without touching its running state. In the Hub, open **Computers**, select the computer, and on its **Overview** tab turn on **Autostart** under **Features**. With `autostart: true`, the computer starts once its server is back after a reboot, maintenance or power failure. Use it for production and always-on computers, not for ones you start on demand ([when to use it](/foundation/computers/managing/reference/#autostart)). ## Read the status log Each entry records `from_status`, `to_status`, `transition_time`, `duration_ms` when known, and `triggered_by`, such as `manual_operation`. On an operation entry (`manual_operation`), `duration_ms` is how long the operation took; on other entries it can be the time since the previous entry. Use the log to find failed states, unexpected stops and slow starts ([fields and queries](/foundation/computers/managing/reference/#status-log)). ## Act on many computers Operations are independent requests, so they can run in parallel within the rate limit; on a `429`, retry after `Retry-After`. The list is paginated, 50 computers per page and 100 at most, with no status filter: filter client-side. In the Hub, select several computers in the **Computers** list and choose **Start**, **Stop** or **Restart**. The action applies to each selected computer whose state and your permissions allow it; **Start** also resumes paused computers. To pause several computers, use the CLI, SDK or API. Pause non-critical computers overnight: ```bash # List computers (paginated; repeat with --page 1, 2, ... through all pages; filter by status client-side) hoody computers list --page 1 --limit 100 # Pause each non-critical computer hoody computers pause "$COMPUTER_ID" # Morning: Resume all paused (page through the list again) hoody computers list --page 1 --limit 100 hoody computers resume "$COMPUTER_ID" ``` ```typescript // Computers to leave running const critical = ['prod-api', 'prod-db']; // List every computer (listAll collects every page) const computers = await client.api.computers.listAll(); // Pause non-critical computers (computers without a name are skipped) for (const c of computers) { if (c.status === 'running' && typeof c.name === 'string' && !critical.includes(c.name)) { await client.api.computers.pause(c.id); } } // Morning: Resume all paused const all = await client.api.computers.listAll(); for (const c of all) { if (c.status === 'paused') { await client.api.computers.resume(c.id); } } ``` ```bash # List all computers (paginated: repeat with page=1, 2, ... through # data.pagination.totalPages; no server-side status filter; filter client-side) curl "https://api.hoody.com/api/v1/computers?page=1&limit=100" \ -H "Authorization: Bearer $HOODY_TOKEN" # Pause each non-critical computer curl -X POST "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/pause" \ -H "Authorization: Bearer $HOODY_TOKEN" # Morning: list again (all pages), filter client-side for status == "paused" curl "https://api.hoody.com/api/v1/computers?page=1&limit=100" \ -H "Authorization: Bearer $HOODY_TOKEN" # Resume each curl -X POST "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/resume" \ -H "Authorization: Bearer $HOODY_TOKEN" ``` List, pause, resume. Route them through the `curl-1` of a running computer that you are not pausing: a paused computer cannot serve the request that resumes it. Scripts that stop idle computers, restart several at once or run maintenance from cron are in [Recipes](/foundation/computers/managing/reference/#recipes). ## Advanced - **[Shutdown deadline](/api/computer-operations/#manage-computer):** `stop` and `restart` wait 60 seconds for a clean exit, then stop forcibly. When processes need longer, send `timeout`, 1 to 600 seconds (`hoody computers stop "$COMPUTER_ID" --timeout 120`). `--timeout 120` gives the computer 120 seconds to shut down cleanly; it does not extend the CLI's default 30-second HTTP wait. If the CLI times out, check the computer's status before retrying. - **[Completion and alerts](/foundation/computers/managing/reference/#wait-until-an-operation-finishes):** the response arrives when the operation is done. After a `504`, poll the status or look for its `computer.operation.completed` or `failed` event; [hoody-notifications](/kit/notifications/) can send you an alert. - **[Recover from crashes](/foundation/computers/managing/reference/#questions):** the API does not restart a crashed computer. Use a monitor outside the computer to detect and restart a stopped computer, systemd inside it for process-level recovery, and `autostart` for recovery when its server starts. - **[Live services and usage](/foundation/computers/managing/reference/#status-log):** `runtime=true` lists sessions and running services; `hoody computers stats` reports CPU and memory. - **[Deploy new code](/foundation/computers/managing/reference/#deploy-new-code):** snapshot first, restart for a clean state, and restore the snapshot if the deploy fails. - **[Switch to a second computer](/foundation/computers/managing/reference/#switch-traffic-blue-to-green):** start it, recreate a proxy alias on it, stop the first. The alias is unavailable briefly while it is recreated. - **[Token permissions](/foundation/computers/managing/reference/#api-calls):** an auth token needs the action permission for each operation it runs. ## Reference States, timings, status log fields, recipes, troubleshooting and a browser tester: the [Managing Computers reference](/foundation/computers/managing/reference/). ## What's next - [Snapshots](/foundation/computers/snapshots/): capture state before operations, restore if needed - [Copy & Sync](/foundation/computers/copy-sync/): duplicate computers for redundancy - [Network Configuration](/foundation/networking/network/): route through proxies - [Hoody Kit Services](/kit/): use the HTTP services