Snapshots
Section titled “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).
Snapshot before an AI agent or a deploy changes the computer, and restore by the name the create call returns:
Prerequisite:
HOODY_TOKENholds an auth token (hdy_…) from the token flow:export HOODY_TOKEN=hdy_….
set -eo pipefail
# 1. Snapshot the current working state and keep its nameBASELINE_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" -yfiimport { 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 nameconst 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 });}set -eo pipefail
# 1. Snapshot the current working state and keep its nameBASELINE_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"fiSnapshot, 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.
# Snapshot the baselinehttps://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":"working-baseline"}&response=transparent
# Create a milestonehttps://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":"with-ai-improvements"}&response=transparent
# Restore the baselinehttps://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/BASELINE_NAME&method=PUT&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
The baseline survives whatever the agent breaks.
In the Hub (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
Section titled “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 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 puts its state elsewhere.
set -eo pipefail
# Capture "right now" before restoring; prints the new snapshot's namecurl -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.
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"# Check computer statuscurl -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 timecurl -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.
# 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 printedSee the errors and the restore effects.
How is a snapshot named?
Section titled “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.
Let a snapshot expire
Section titled “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.
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 statefiimport { 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}set -eo pipefail
# Before deployment: a snapshot that expires in 30 days. Keep its exact nameSNAPSHOT_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 statefiSnapshot 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.
# Pre-deploy 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-v2.1.0","expiry":30}&response=transparent
# Snapshot before rolling backhttps://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":"before-rollback"}&response=transparent
# Roll backhttps://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/SNAPSHOT_NAME&method=PUT&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
Before relying on an old snapshot, check that it is still listed and its expires_at. Suggested terms.
List and delete snapshots
Section titled “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). 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?
Section titled “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
Section titled “Start a new computer from a snapshot”Pass a snapshot’s name as source_snapshot to the copy call 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.
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. 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.
set -eo pipefail
# Snapshot as permanent template, capturing the snapshot nameTEMPLATE_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 ownhoody computers copy "$TEMPLATE_ID" \ --target-project "$TARGET_PROJECT_ID" \ --name "new-dev-env" \ --source-snapshot "$TEMPLATE_SNAPSHOT_NAME"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 ownawait client.api.computers.copy(templateId, { target_project_id: process.env.TARGET_PROJECT_ID!, name: 'new-dev-env', source_snapshot: templateSnapshot.data.snapshot!.name!});set -eo pipefail
# Snapshot as permanent template, capturing the snapshot nameTEMPLATE_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 owncurl -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.
# Create template snapshothttps://PROJECT_ID-COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/computers/TEMPLATE_ID/snapshots&method=POST&bearer_token=HOODY_TOKEN&json={"alias":"dev-template-2025"}&response=transparent
# Copy from templatehttps://PROJECT_ID-COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/computers/TEMPLATE_ID/copy&method=POST&bearer_token=HOODY_TOKEN&json={"target_project_id":"TARGET_PROJECT_ID","name":"new-dev-env","source_snapshot":"TEMPLATE_SNAPSHOT_NAME"}&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
The copy finishes in the background (Copy & Sync). Snapshot or copy?
How many snapshots can I create?
Section titled “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, 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; 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.
Advanced
Section titled “Advanced”- Token and collaborator access: a script or agent’s auth token needs
computers.features.snapshots, pluscomputers.readto list orcomputers.updateto change snapshots. A project collaborator needsreadto list andeditto create, restore, delete or relabel snapshots. See access. - Daily backups: a scheduled script takes a dated snapshot with an
expiry. Fit it tomax_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. - Rollback inside a deploy: a function that snapshots, deploys, health-checks and restores on failure. See the deploy recipe.
- Milestones and branches: permanent snapshots such as
v1.0.0-stablegive the computer a version history. See 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.
Reference
Section titled “Reference”Fields, limits, errors, recipes and troubleshooting: the Snapshots reference.
What’s next
Section titled “What’s next”- Copy & Sync: duplicate computers
- Concepts: Snapshots: how snapshots are stored
- Managing Computers: start, stop and restart
- Create, Edit, Delete: computer fundamentals