Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

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.

Start a computer in the morning and pause it in the evening:

Terminal window
# 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"

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:

StateUsual next operations
runningstop, force-stop, restart, pause, delete
stoppedstart, restart, delete
pausedresume, 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 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.

POST Start a stopped computer
/api/v1/computers/{computer_id}/start
Click "Run" to execute the request

The response carries the computer’s new status:

{
"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.

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.

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:

Terminal window
# 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"
POST Restart a computer
/api/v1/computers/{computer_id}/restart
Click "Run" to execute the request

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.

POST Pause a running computer
/api/v1/computers/{computer_id}/pause
Click "Run" to execute the request
POST Resume a paused computer
/api/v1/computers/{computer_id}/resume
Click "Run" to execute the request

Pause freezes every process with its state in RAM; resume continues exactly where it paused.

Pause and resumeStop and start
ProcessesFrozen, then continueTerminated
RAM state and open filesPreservedLost or closed; the filesystem is preserved
Network connectionsCan time out while paused; reconnect after resumingClosed
SnapshotsNot while paused: resume or stop firstAllowed
Best forQuick suspensionMaintenance, 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.

Usually not. After a successful live sync, new exec and console processes see changed environment variables at once, and computers 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. 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.

Terminal window
# 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"
Terminal window
# Enable autostart
hoody computers update "$COMPUTER_ID" --autostart

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).

GET Get computer status transition history
/api/v1/computers/{computer_id}/status-logs
Click "Run" to execute the request

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).

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:

Terminal window
# 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"

Scripts that stop idle computers, restart several at once or run maintenance from cron are in Recipes.

  • Shutdown deadline: 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: 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 can send you an alert.
  • Recover from crashes: 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: runtime=true lists sessions and running services; hoody computers stats reports CPU and memory.
  • Deploy new code: snapshot first, restart for a clean state, and restore the snapshot if the deploy fails.
  • Switch to a second computer: start it, recreate a proxy alias on it, stop the first. The alias is unavailable briefly while it is recreated.
  • Token permissions: an auth token needs the action permission for each operation it runs.

States, timings, status log fields, recipes, troubleshooting and a browser tester: the Managing Computers reference.