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 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_TOKEN holds an auth token (hdy_…) from the token flow: export HOODY_TOKEN=hdy_….

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

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.

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.

Terminal window
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.

See the errors and the restore effects.

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.

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.

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

Before relying on an old snapshot, check that it is still listed and its expires_at. Suggested terms.

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.

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.

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.

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

The copy finishes in the background (Copy & Sync). Snapshot or copy?

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.

  • 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.
  • 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.
  • 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-stable give 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.

Fields, limits, errors, recipes and troubleshooting: the Snapshots reference.