# Snapshots **Page:** foundation/computers/snapshots [Download Raw Markdown](./foundation/computers/snapshots.md) --- # Snapshots A snapshot records a computer's filesystem at a point in time. Restoring one puts files, packages and on-disk data back as they were, so an unwanted change costs a single call to undo ([the model](/concepts/snapshots/)). Snapshot before an AI agent or a deploy changes the computer, and restore by the `name` the create call returns: > **Prerequisite:** `HOODY_TOKEN` holds an auth token (`hdy_…`) from the [token flow](/foundation/hoody-api/authentication/#automation-and-ai-agents-recommended): `export HOODY_TOKEN=hdy_…`. ```bash set -eo pipefail # 1. Snapshot the current working state and keep its name BASELINE_NAME=$(hoody snapshots create -c "$COMPUTER_ID" \ --alias "working-baseline" -o json | jq -r '.snapshot.name') # 2. Let the AI agent make changes... then set AI_OK=1 if you keep them if [ "${AI_OK:-0}" = 1 ]; then # 3. The changes work: create a new milestone hoody snapshots create -c "$COMPUTER_ID" --alias "with-ai-improvements" else # They broke something: restore the baseline by its name # `-y` skips the destructive-operation confirmation prompt, required in scripts and agents. # After 30 s the CLI can report a timeout while the restore carries on. # Do not resend it; another restore can return 409 while the first is running. hoody snapshots restore "$BASELINE_NAME" -c "$COMPUTER_ID" -y fi ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const computerId = process.env.COMPUTER_ID!; // 1. Snapshot the current working state, capturing the snapshot name const baseline = await client.api.snapshots.create(computerId, { alias: 'working-baseline' }); const baselineName = baseline.data.snapshot!.name!; // 2. Let the AI agent make changes... then set AI_OK=1 if you keep them if (process.env.AI_OK === '1') { // 3. The changes work: create a new milestone await client.api.snapshots.create(computerId, { alias: 'with-ai-improvements' }); } else { // They broke something: restore the baseline by its name. // timeoutMs: 0 waits past the default 30 s; a restore over about a minute throws while it carries on await client.api.snapshots.restore(computerId, baselineName, { timeoutMs: 0, responseIsFinal: true }); } ``` ```bash set -eo pipefail # 1. Snapshot the current working state and keep its name BASELINE_NAME=$(curl -sf -X POST "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/snapshots" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"alias": "working-baseline"}' | jq -r '.data.snapshot.name') # 2. Let the AI agent make changes... then set AI_OK=1 if you keep them if [ "${AI_OK:-0}" = 1 ]; then # 3. The changes work: create a new milestone curl -sf -X POST "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/snapshots" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"alias": "with-ai-improvements"}' else # They broke something: restore the baseline by its name curl -sf -X PUT "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/snapshots/$BASELINE_NAME" \ -H "Authorization: Bearer $HOODY_TOKEN" fi ``` Snapshot, then snapshot again if the agent's changes look good, or restore the baseline. Replace BASELINE_NAME with the first link's `name`. The links run through another computer's `curl-1`, because a restore restarts this one. The baseline survives whatever the agent breaks. In the Hub ([hub.hoody.com](https://hub.hoody.com)), open **Computers**, select the computer and open the **Backups** tab. **Take snapshot** opens **Take a snapshot**: enter a **Name**, optionally **Delete after (days)**, and press **Take snapshot**. To roll back, press **Restore** on the snapshot row, then **Restore computer**. ## Restore a snapshot A restore discards the current filesystem and puts the snapshot's in its place, on-disk configuration included. Environment variables you configured through Hoody keep their current values and are reapplied after the restore. A running computer is stopped and started again, so processes start fresh; a stopped one stays stopped. A small restore finishes in seconds, inside the call. A large one can take many minutes and carries on after the call ends: the CLI and SDK stop waiting after 30 seconds, and the API closes a request that stays silent for about a minute. Never send it again; [check that it finished](/foundation/computers/snapshots/reference/#troubleshooting) first. The path takes the `name` from create or list, never the alias. A restore works only on the snapshot's own computer; a [copy](#start-a-new-computer-from-a-snapshot) puts its state elsewhere. Restoring is destructive: the computer's current state is lost. Snapshot that state first if you want to be able to return to it, and restore only once that snapshot exists. ```bash set -eo pipefail # Capture "right now" before restoring; prints the new snapshot's name curl -sf -X POST "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/snapshots" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"alias": "before-restore"}' | jq -r '.data.snapshot.name' ``` Now you can restore to either state. Go on only if this printed a name. ```bash set -eo pipefail # Restore to the target snapshot (use the exact `name` returned by create/list) curl -sf -X PUT "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/snapshots/$SNAPSHOT_NAME" \ -H "Authorization: Bearer $HOODY_TOKEN" ``` ```bash # Check computer status curl -sf "https://api.hoody.com/api/v1/computers/$COMPUTER_ID" \ -H "Authorization: Bearer $HOODY_TOKEN" | jq -r '.data.status' # Expect the status it had before the restore: "running" if it was running, "stopped" if it was stopped # The status alone does not show which snapshot was restored: check that the # target's last_used_at now shows the restore time curl -sf "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/snapshots" \ -H "Authorization: Bearer $HOODY_TOKEN" \ | jq -r --arg n "$SNAPSHOT_NAME" '.data.snapshots[] | select(.name == $n) | .last_used_at' ``` If your client timed out and `last_used_at` has not moved, check the files before you restore again. ```bash # Access via service URLs # https://$PROJECT_ID-$COMPUTER_ID-terminal-1.$SERVER.computers.hoody.com # Verify everything works as expected # If issues, restore the "before-restore" snapshot by the name step 1 printed ``` See the [errors](/foundation/computers/snapshots/reference/#errors) and the [restore effects](/foundation/computers/snapshots/reference/#what-a-restore-changes). ## How is a snapshot named? With an `alias`, the snapshot's `name` is the alias stripped to letters, digits, `_` and `-`: `"My Backup"` becomes `MyBackup`, and `pre-deploy` stays `pre-deploy`. Leading and trailing `-` and `_` go, and the name is cut to 64 characters. Without one, or when the strip leaves nothing, Hoody generates `snap-YYYYMMDD-HHMMSS`, such as `snap-20251109-143045`. An alias that contains control or invisible characters is refused with `400`, and so is one whose strip leaves exactly one character. Restore, delete and the alias update take this `name`. The alias (up to 100 characters) is a label, for example to mark a snapshot known-good after testing: `hoody snapshots alias set` or `PUT /api/v1/computers/{id}/snapshots/{name}/alias` changes it, or clears it with `null` (`--alias null`), without renaming the snapshot. See the [naming rules](/foundation/computers/snapshots/reference/#naming). ## Let a snapshot expire Pass `expiry` as a whole number of days (1 to 3650) to request automatic expiry. When the term is up, the snapshot is deleted: its storage is freed and it can no longer be restored. Confirm `expires_at` with a list call afterwards: a successful create can leave it `null`, which means the snapshot does not expire and you must delete it yourself. Omit `expiry` for a permanent snapshot. Expiry suits experiment backups, pre-deploy snapshots and rotations you would otherwise clean up by hand. ```bash set -eo pipefail # Before deployment: a snapshot that expires in 30 days. Keep its name: # the alias "pre-deploy-v2.1.0" becomes the name "pre-deploy-v210" SNAPSHOT_NAME=$(hoody snapshots create -c "$COMPUTER_ID" \ --alias "pre-deploy-v2.1.0" --expiry 30 -o json | jq -r '.snapshot.name') # Deploy via terminal/SSH, then set DEPLOY_OK=1 if it works... if [ "${DEPLOY_OK:-0}" != 1 ]; then # Keep the current state first: a restore discards everything written since the snapshot hoody snapshots create -c "$COMPUTER_ID" --alias "before-rollback-$(date +%s)" # `-y` skips the destructive-operation confirmation prompt, required in scripts and agents. # After 30 s the CLI can report a timeout while the restore carries on. # Do not resend it; another restore can return 409 while the first is running. hoody snapshots restore "$SNAPSHOT_NAME" -c "$COMPUTER_ID" -y # Production rolled back to the snapshot state fi ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const computerId = process.env.COMPUTER_ID!; // Before deployment. Capture the returned snapshot name: with an alias, the // name is the alias stripped to letters, digits, _ and - ("pre-deploy-v210" here). const preDeploy = await client.api.snapshots.create(computerId, { alias: 'pre-deploy-v2.1.0', expiry: 30 }); const preDeploySnapshotName = preDeploy.data.snapshot!.name!; // Deploy via terminal, then set DEPLOY_OK=1 if it works... const deployOk = process.env.DEPLOY_OK === '1'; if (!deployOk) { // Keep the current state first: a restore discards everything written since the snapshot await client.api.snapshots.create(computerId, { alias: `before-rollback-${Date.now()}` }); // timeoutMs: 0 waits past the default 30 s; a restore over about a minute throws while it carries on await client.api.snapshots.restore(computerId, preDeploySnapshotName, { timeoutMs: 0, responseIsFinal: true }); // Production rolled back to the snapshot state } ``` ```bash set -eo pipefail # Before deployment: a snapshot that expires in 30 days. Keep its exact name SNAPSHOT_NAME=$(curl -sf -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-v2.1.0", "expiry": 30}' | jq -r '.data.snapshot.name') # Deploy via terminal/SSH, then set DEPLOY_OK=1 if it works # https://$PROJECT_ID-$COMPUTER_ID-terminal-1.$SERVER.computers.hoody.com if [ "${DEPLOY_OK:-0}" != 1 ]; then # Keep the current state first: a restore discards everything written since the snapshot curl -sf -X POST "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/snapshots" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"alias": "before-rollback-'"$(date +%s)"'"}' curl -sf -X PUT "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/snapshots/$SNAPSHOT_NAME" \ -H "Authorization: Bearer $HOODY_TOKEN" # Production rolled back to the snapshot state fi ``` Snapshot before the deploy. If an issue turns up, snapshot the current state under a new alias, and roll back only once that returns a `name`. Replace SNAPSHOT_NAME with the first link's `name`. The links run through another computer's `curl-1`. Before relying on an old snapshot, check that it is still listed and its `expires_at`. [Suggested terms](/foundation/computers/snapshots/reference/#suggested-expiry). ## List and delete snapshots `hoody snapshots list -c "$COMPUTER_ID" -o json` or `GET /api/v1/computers/{id}/snapshots` returns each snapshot's `name`, `alias`, `created_at`, `last_used_at`, `expires_at`, `stateful` and `size` ([fields](/foundation/computers/snapshots/reference/#snapshot-fields)). Without `-o json`, the interactive CLI table shows name, alias and creation time. `hoody snapshots delete "$SNAPSHOT_NAME" -c "$COMPUTER_ID" -y` or `DELETE /api/v1/computers/{id}/snapshots/{name}` removes the captured filesystem state and its metadata (alias, timestamps). Storage reclamation may take time; data the computer or other snapshots still need stays. A delete cannot be undone, and the `name` stops resolving. In the Hub, the computer's **Backups** tab lists its snapshots. A row's ⋯ menu has **Rename label**, which changes the alias and leaves the name as it is, and **Delete**, confirmed with **Delete snapshot**. ## What does a snapshot capture? Everything on the computer's disk: files, database files as written at that moment, configuration and environment files, installed packages. Snapshots are filesystem-only (stateless): no RAM, running processes or in-flight network connections, so `stateful` is always `false`. Creation is close to instant on a running or stopped computer, and a running one keeps running. A paused computer is rejected: resume or stop it first. Flush a database or queue that holds data in memory, or stop it or the computer, so the captured disk is consistent. ## Start a new computer from a snapshot Pass a snapshot's name as `source_snapshot` to the [copy call](/foundation/computers/copy-sync/#copy-from-a-specific-snapshot) and the new computer starts from that state instead of the live disk. The copy is independent: it can run on another server or project, and survives its source. Snapshots are deleted with their computer: deleting a computer permanently deletes all of its snapshots. To keep a state, copy the computer first. A snapshot lives on its computer's server, so it is a rollback point, not an off-server backup; for disaster recovery, add a [copy onto another server](/foundation/computers/copy-sync/#cross-server-copy). To hand out one prepared environment, copy the template into a destination project you own. You must own both the source and destination projects; collaborator access is not enough. In the Hub, open the source computer's **Backups** tab, choose **New computer from this** on the snapshot row, pick the **Name**, **Server** and **Project**, and press **Make the computer**. The new computer shows as copying until it is ready. ```bash set -eo pipefail # Snapshot as permanent template, capturing the snapshot name TEMPLATE_SNAPSHOT_NAME=$(hoody snapshots create -c "$TEMPLATE_ID" \ --alias "dev-template-2025" -o json | jq -r '.snapshot.name') # Copy from this snapshot into a destination project you own hoody computers copy "$TEMPLATE_ID" \ --target-project "$TARGET_PROJECT_ID" \ --name "new-dev-env" \ --source-snapshot "$TEMPLATE_SNAPSHOT_NAME" ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const templateId = process.env.TEMPLATE_ID!; // Snapshot as permanent template (omit `expiry` for no expiration) const templateSnapshot = await client.api.snapshots.create(templateId, { alias: 'dev-template-2025' }); // Copy from this snapshot into a destination project you own await client.api.computers.copy(templateId, { target_project_id: process.env.TARGET_PROJECT_ID!, name: 'new-dev-env', source_snapshot: templateSnapshot.data.snapshot!.name! }); ``` ```bash set -eo pipefail # Snapshot as permanent template, capturing the snapshot name TEMPLATE_SNAPSHOT_NAME=$(curl -sf -X POST "https://api.hoody.com/api/v1/computers/$TEMPLATE_ID/snapshots" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"alias": "dev-template-2025"}' | jq -r '.data.snapshot.name') # Copy from this snapshot into a destination project you own curl -sf -X POST "https://api.hoody.com/api/v1/computers/$TEMPLATE_ID/copy" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "target_project_id": "'"$TARGET_PROJECT_ID"'", "name": "new-dev-env", "source_snapshot": "'"$TEMPLATE_SNAPSHOT_NAME"'" }' ``` Snapshot the configured computer once, then repeat the copy link for destination projects you own. Replace TEMPLATE_SNAPSHOT_NAME with the first link's `name`. The copy finishes in the background ([Copy & Sync](/foundation/computers/copy-sync/)). [Snapshot or copy?](/foundation/computers/snapshots/reference/#snapshots-or-a-copy) ## How many snapshots can I create? Each computer holds up to `max_snapshots`, which the list returns: 2 on free-tier servers, the plan's `snapshots_per_computer` on a [paid subserver](/foundation/servers/paid-subservers/), and 1000 elsewhere. One more create returns `400` `COMPUTER_SNAPSHOT_LIMIT`; delete one, or let expiry clean up. Snapshots count toward your total storage, like any other storage you use. Disk limits and prices are on [Pricing](/foundation/pricing/#what-does-each-limit-count); delete snapshots you no longer need. Snapshot writes share an account-wide limit, by default 50 per 5 minutes; over it, `429` creates nothing: wait, resend, and queue large fleets. [All limits](/foundation/computers/snapshots/reference/#limits). ## Advanced - **Token and collaborator access:** a script or agent's auth token needs `computers.features.snapshots`, plus `computers.read` to list or `computers.update` to change snapshots. A project collaborator needs `read` to list and `edit` to create, restore, delete or relabel snapshots. See [access](/foundation/computers/snapshots/reference/#access). - **Daily backups:** a scheduled script takes a dated snapshot with an `expiry`. Fit it to `max_snapshots`: with a cap of 25, 30 dailies do not fit, so the recipe deletes the oldest one when the computer is full. See the [backup recipe](/foundation/computers/snapshots/reference/#daily-automated-backups). - **Rollback inside a deploy:** a function that snapshots, deploys, health-checks and restores on failure. See the [deploy recipe](/foundation/computers/snapshots/reference/#deploy-with-automatic-rollback). - **Milestones and branches:** permanent snapshots such as `v1.0.0-stable` give the computer a version history. See [branch points](/foundation/computers/snapshots/reference/#branch-points). - **Cleanup by age:** a script that deletes expiring snapshots older than 30 days, sooner than their term, and keeps permanent ones. See the [cleanup recipe](/foundation/computers/snapshots/reference/#clean-up-old-snapshots). ## Reference Fields, limits, errors, recipes and troubleshooting: the [Snapshots reference](/foundation/computers/snapshots/reference/). ## What's next - [Copy & Sync](/foundation/computers/copy-sync/): duplicate computers - [Concepts: Snapshots](/concepts/snapshots/): how snapshots are stored - [Managing Computers](/foundation/computers/managing/): start, stop and restart - [Create, Edit, Delete](/foundation/computers/create-edit-delete/): computer fundamentals