Snapshots reference
Section titled “Snapshots reference”Lookup tables for snapshots. Every field and status code is in the Computer Snapshots API.
API calls
Section titled “API calls”| Task | HTTP | CLI | SDK |
|---|---|---|---|
| List all snapshots | GET /api/v1/computers/{id}/snapshots | hoody snapshots list | client.api.snapshots.list(id) |
| Create new snapshot | POST /api/v1/computers/{id}/snapshots | hoody snapshots create --alias … --expiry … | client.api.snapshots.create(id, { alias, expiry }) |
| Restore from snapshot | PUT /api/v1/computers/{id}/snapshots/{name} (also PATCH) | hoody snapshots restore "$SNAPSHOT_NAME" -y | client.api.snapshots.restore(id, name) |
| Delete snapshot | DELETE /api/v1/computers/{id}/snapshots/{name} | hoody snapshots delete "$SNAPSHOT_NAME" -y | client.api.snapshots.delete(id, name) |
Update snapshot alias, or clear it with null | PUT /api/v1/computers/{id}/snapshots/{name}/alias (also PATCH) | hoody snapshots alias set "$SNAPSHOT_NAME" --alias … | client.api.snapshots.setAlias(id, name, { alias }) |
| Computer details | GET /api/v1/computers/{id} | hoody computers get | client.api.computers.get(id) |
| Copy a computer, optionally from a specific snapshot | POST /api/v1/computers/{id}/copy with target_project_id and optional source_snapshot | hoody computers copy "$SOURCE_ID" --target-project "$PROJECT_ID" --source-snapshot "$SNAPSHOT_NAME" | client.api.computers.copy(id, { target_project_id: projectId, source_snapshot }) |
The snapshot commands take the computer with -c (--computer) or $HOODY_COMPUTER_ID. restore and delete ask for confirmation; -y skips the prompt and is required in scripts and agents.
The list returns details for each snapshot. Sort by created_at when you need chronological order. Both create fields are optional: omit alias and the name is auto-generated, omit expiry and the snapshot is permanent. Restore, delete and the alias update take the snapshot’s name as returned by GET /api/v1/computers/{id}/snapshots; when in doubt, list the snapshots and pass the exact name field. After a delete, storage reclamation may take time; data the computer or other snapshots still need stays.
In the Hub, open Computers, select your computer, and open Backups. In Snapshots, choose Take snapshot, enter a name and optional Delete after (days), then choose Take snapshot. Use Restore on a snapshot to restore it and confirm with Restore computer. Its row menu also offers New computer from this, Rename label and Delete.
Access
Section titled “Access”| Caller | List | Create, restore, delete, alias update |
|---|---|---|
| You, as the computer’s owner | Yes | Yes |
| Auth token | Needs computers.read and computers.features.snapshots | Needs computers.update and computers.features.snapshots |
| Project collaborator | read permission or higher | edit permission or higher |
An auth token also needs computers.features.snapshots to copy with source_snapshot. A token limited to realms calls through its realm’s URL, https://{realmId}.api.hoody.com. The HTTP examples assume HOODY_TOKEN holds a valid auth token (token flow).
Naming
Section titled “Naming”| Rule | Detail |
|---|---|
| The key | name is what restore, delete, the alias update and a copy’s source_snapshot take, never the alias. Take it from the name field returned by create or list: it is exact even when sanitization changed the alias |
| Name from an alias | The sanitized alias becomes the snapshot’s name: letters, digits, _ and - are kept, leading - and _ are stripped, the result is cut to 64 characters, then trailing - and _ are stripped. "My Backup" becomes MyBackup; pre-deploy-v2.1.0 becomes pre-deploy-v210; a clean alias like pre-deploy stays the same |
| Too short | An alias that sanitizes to exactly one character is refused with 400. If sanitization leaves nothing, Hoody generates a timestamped name |
| Generated name | Without an alias, or when the strip leaves nothing: snap-YYYYMMDD-HHMMSS in UTC, such as snap-20251109-143045. Chronologically sortable, but names generated in the same second can collide |
| Alias | Optional; max 100 characters; examples "pre-deploy", "working-state", "before-ai-changes". An alias with control or invisible characters is refused with 400 |
| Unique | Another snapshot of the same computer cannot already use the alias, or the name it becomes (400) |
| Changing the alias | The alias update (PUT or PATCH) sets or changes it after creation, or clears it with null, without renaming the snapshot. It returns 409 with COMPUTER_EXPIRED once its server ended or was reinstalled, or computer_finalizing while computer setup is still in progress |
| In the list | The alias field carries the alias given at create, or the one set later by the alias update call |
Make the alias descriptive: the sanitized alias becomes the snapshot’s name, the key you restore and delete by, and list also returns the alias as given. Both are what you have to go on when you pick a snapshot to restore months later.
# Good aliases (context-rich){"alias": "pre-deploy-v2.1.0-2025-11-09"}{"alias": "before-database-migration"}{"alias": "working-state-ai-approved"}
# Poor aliases (vague){"alias": "backup"}{"alias": "test"}{"alias": "snapshot1"}Snapshot fields
Section titled “Snapshot fields”| Field | Meaning |
|---|---|
name | The restore/delete key: the sanitized alias when one was supplied, else a generated snap-YYYYMMDD-HHMMSS name |
alias | The snapshot’s label: the alias given at create, or the one set later by the alias-update call; null when no alias was given or it was cleared. Relabelling never renames the snapshot |
created_at | When the snapshot was taken |
last_used_at | When the snapshot was last restored (null if never) |
expires_at | Auto-deletion date (null if permanent) |
stateful | Whether a RAM/process state was captured. Hoody snapshots are filesystem-only, so this is always false |
size | Storage space used, in bytes; -1 means the size is unavailable |
snapshot_count | List only: how many snapshots the computer holds now |
max_snapshots | List only: the computer’s snapshot cap (Limits) |
The create call returns as soon as the snapshot exists, whether the computer is running or stopped. Response:
{ "statusCode": 201, "message": "Snapshot created successfully", "data": { "computer_id": "890abcdef12345678901cdef", "project_id": "67e89abc123def456789abcd", "snapshot": { "name": "production-stable", "alias": "production-stable", "created_at": "2025-11-09T14:30:45.000Z", "last_used_at": null, "expires_at": "2026-02-07T14:30:45.000Z", "stateful": false, "size": 4589764321 } }}The list call, response:
{ "statusCode": 200, "message": "Snapshots retrieved successfully", "data": { "computer_id": "890abcdef12345678901cdef", "project_id": "67e89abc123def456789abcd", "snapshots": [ { "name": "before-ai-refactor", "alias": "before-ai-refactor", "created_at": "2025-11-08T10:00:00.000Z", "last_used_at": null, "expires_at": "2025-12-07T10:00:00.000Z", "stateful": false, "size": 4123456789 }, { "name": "production-stable", "alias": "production-stable", "created_at": "2025-11-09T14:30:45.000Z", "last_used_at": "2025-11-09T16:15:00.000Z", "expires_at": "2026-02-07T14:30:45.000Z", "stateful": false, "size": 4589764321 } ], "snapshot_count": 2, "max_snapshots": 25 }}max_snapshots is null when the cap cannot be read at that moment.
Limits
Section titled “Limits”| Limit | Value |
|---|---|
| Snapshots per computer | The snapshot cap enforced by the API, returned as max_snapshots by the list call. 2 per computer by default on free-tier servers; the plan’s snapshots_per_computer on a paid subserver; 1000 elsewhere, far higher than the free tier. The free and rented figures can change. One more create returns 400 COMPUTER_SNAPSHOT_LIMIT |
| Computer state for a create | running or stopped. A paused computer has to be resumed or stopped first |
alias | At most 100 characters |
| Snapshot name | 2 to 64 characters |
expiry | Whole days, 1 to 3650; a value outside is refused before the snapshot is created. Omitted: permanent |
| Write limit | Snapshot create, restore, delete and alias update share one account-wide limit, by default 5 requests per 5 minutes; a server can apply a different limit. A request over it returns 429; nothing is created, so wait and send it again. Batch large fleets through a queue rather than firing every request at once |
A snapshot holds the computer’s disk, not its memory. 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.
What a restore changes
Section titled “What a restore changes”| Part | After a restore |
|---|---|
| Filesystem | The computer’s own filesystem is replaced by the snapshot’s filesystem, including on-disk configuration. Data mounted from other computers is not captured or rolled back; back up that data on its source computer |
| A running computer | Stopped and started again from that filesystem; processes do not resume mid-execution |
| A stopped computer | Stays stopped |
| Memory | Anything that was only in memory at snapshot time is not restored |
| Changes after the snapshot | Not included: the snapshot captures only its moment |
| Environment variables set through the API | Not rolled back: the current ones are applied again after the restore |
| Proxy aliases and permissions | Not part of the snapshot and not changed by a restore; they stay as they are |
last_used_at of the snapshot | Normally set to the time of the restore |
| Other snapshots | Kept; you can restore to any of them |
| Duration | Restoration time depends on the snapshot’s size and on how much the disk has changed since it was taken: small restores finish in seconds, inside the call; very large ones can take many minutes. The restore 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. See Troubleshooting before sending it again |
A snapshot records everything on a computer’s disk at a specific moment. Each point on this line is a snapshot, and restoring one returns the disk to that moment:
Yesterday ──→ 3 hours ago ──→ 1 hour ago ──→ NOW ● ● ● ●Snapshots are stateless, meaning filesystem-only, which is why the create call works in either computer state:
# Works whether the computer is running or stoppedcurl -X POST "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/snapshots" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{}'Snapshots or a copy
Section titled “Snapshots or a copy”| Snapshot | Computer copy | |
|---|---|---|
| Purpose | Roll a computer back to an earlier disk state | Duplicate the entire computer |
| Creation | Instant (seconds) | Slower (minutes) |
| Storage | Incremental | An independent filesystem; storage use depends on where the copy is created and subsequent changes |
| Where it lives | Built into the computer and tied to it; cannot run independently | An independent computer; can run on a different server and be in a different project |
| Source deleted | Deleted with the computer (cascade delete) | Survives source deletion |
| Restoration | Fast | |
| Use for | Backup/restore, experimenting safely, rollback mechanism, version milestones | Creating staging from prod, disaster recovery (different server), team environments (same setup), production redundancy |
A copy can start from a specific snapshot instead of the computer’s live disk. See Copy & Sync for duplication workflows.
# Create computer from specific snapshotPOST /api/v1/computers/{source_id}/copy{ "target_project_id": "{project_id}", "name": "restored-copy", "source_snapshot": "snap-20251109-143045"}Errors
Section titled “Errors”| Status and code | When | What to do |
|---|---|---|
400 COMPUTER_SNAPSHOT_LIMIT | Create: the computer already holds max_snapshots | Delete an existing snapshot on this computer first |
400 | Create on a computer that is not running or stopped, such as a paused one | Resume or stop it first |
400 | An alias that is already in use on the computer, that sanitizes to exactly one character, or that holds control or invisible characters | Choose another alias |
403 INSUFFICIENT_PERMISSIONS | Your account or token lacks the access in Access | Ask the owner for access, or use a token with the permissions |
403 | Restore: the computer’s owner no longer has access to its server | Copy it to a server the owner holds, or delete it |
404 | No snapshot of that name on the computer. When the value is another snapshot’s alias, the message names that snapshot’s name | List the snapshots and pass the exact name |
409 SNAPSHOT_OPERATION_IN_PROGRESS | Create: another snapshot operation may be running, or the service is temporarily unavailable. Nothing was created | Retry after a few seconds, using the Retry-After header when it is present |
409 RESOURCE_ALREADY_EXISTS | Create without an alias: the generated name is already in use, for example after a second create in the same second | Retry in a moment, or give the snapshot an alias |
409 COMPUTER_OPERATION_IN_PROGRESS | Restore or delete: another operation, such as an earlier restore, is running on the computer. Nothing was done | Wait for it to finish; after a client timeout, see Troubleshooting before restoring again |
409 OPERATION_STATE_CONFLICT | Restore: the computer is in a state that cannot be restored, such as one still being created; nothing was changed | Wait until it is in a restorable state, then retry |
409 COMPUTER_NETWORK_POLICY_MISSING | Restore: the computer has no network policy in force. Nothing was changed | Configure its network with PUT /api/v1/computers/{id}/network, then retry |
409 COMPUTER_EXPIRED | Create, restore, delete or alias update on a computer that expired when its server ended or was reinstalled. Nothing was changed | Create a new computer; the expired one cannot be operated again |
409 computer_finalizing | The computer is still being set up | Retry in a few seconds |
409 SUBSERVER_DORMANT | The computer is on a paid subserver whose subscription is not active | Retry once the subserver is active again |
429 | Over the write limit. Nothing was created | Wait and send it again |
503 SNAPSHOT_INVENTORY_UNAVAILABLE | Create or alias update: the computer’s snapshot list could not be read. No changes were made | Retry shortly; contact support if it persists |
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | What to do |
|---|---|---|
Snapshot creation, restore or deletion returns 409 COMPUTER_EXPIRED | The computer expired when its server ended or was reinstalled; nothing was changed | Create a new computer; the expired one cannot be operated again |
| Snapshot creation fails | Not enough storage | Check disk total and usage with GET /api/v1/computers/{id}/stats (hoody computers stats): verify the computer has available storage |
| Snapshot creation fails | Computer status | Check GET /api/v1/computers/{id}: status should be running or stopped, not failed/creating |
| Snapshot creation fails | Permissions | Ensure you own the computer (or have the access), and check that the auth token is valid |
| Restore runs longer than you expect | Restore time varies widely with snapshot size and with how far the disk has diverged since it was taken | Check the snapshot’s size with GET /api/v1/computers/{id}/snapshots: large snapshots (>100 GB) take longer. Wait longer: very large restores can take many minutes. An active rental status does not confirm server availability. If the restore remains unresolved, contact support with the computer ID and the time of the request |
| Your client gave up waiting for a restore | The restore carries on after your client stops waiting, and a second one while it runs is refused with 409 COMPUTER_OPERATION_IN_PROGRESS | Do not send it again. Once it finishes, last_used_at normally shows its time; if it does not, check the computer’s files before restoring again |
Restore returns 404 Not Found | Wrong snapshot name | List snapshots to get the exact name with GET /api/v1/computers/{id}/snapshots, and use the “name” field exactly as returned. With an alias, the name is the alias stripped to letters, digits, _ and - (so “My Backup” becomes “MyBackup”): leading - and _ are stripped, the result is cut to 64 characters, then trailing - and _ are stripped; without one, or if the strip leaves nothing, Hoody generates snap-YYYYMMDD-HHMMSS |
Restore returns 404 Not Found | The snapshot expired or was deleted | Verify the snapshot is still in the list and its expires_at hasn’t passed |
| Snapshot storage costs are high | Old or unused snapshots | Delete old/unused snapshots: list snapshots sorted by age, then delete snapshots you no longer need (Practices) with DELETE /api/v1/computers/{id}/snapshots/{old_snapshot_name}. Set expiration on new snapshots, such as {"alias": "temp-backup", "expiry": 7}. Trim the computer filesystem before snapshotting (clear caches, logs, build artifacts) to reduce snapshot size: clean package caches and temp files inside the computer, then create the snapshot |
| Restored computer is not what you expected | Restored wrong snapshot | Verify the snapshot name passed to the restore operation: restore keys on name only, never on alias. Re-list snapshots and confirm the intended one was targeted |
| Restored computer is not what you expected | Snapshots are filesystem-only | Running processes and in-memory state are never included; only the filesystem is restored, and the computer starts fresh from that filesystem |
| Restored computer is not what you expected | Post-snapshot changes | The snapshot captures only that moment; changes made afterwards are not included. Verify the snapshot’s created_at timestamp |
Practices
Section titled “Practices”Snapshot before destructive filesystem changes, such as force-stopping a computer (Managing Computers), dependency updates, database migrations, deployments or a change of base software (Images). A snapshot holds the filesystem only. Restoring it does not roll back network or firewall settings, so note those before you change them:
# Always snapshot before:curl -X POST "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/snapshots" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{}'
# Then:- force-stop operations- major configuration changes- dependency updates (npm, apt, pip)- database migrations- letting AI modify code- production deployments| Decision | When |
|---|---|
| Delete a snapshot | Once it is a spent temporary backup, once a newer snapshot supersedes it, once an old experiment branch is finished, or whenever you need the storage back |
| Keep a snapshot | When it is your long-term rollback point, when compliance or audit rules require it, when it serves as a template for new computers, or when it records an architecture decision or configuration you may want to look up later |
The returned list is what you drive cleanup from: monitor snapshot accumulation (response.data.snapshots.length), trigger cleanup when the count is high, and verify a specific snapshot exists before restore. An old snapshot may have expired or been deleted, so check before you rely on it:
set -eo pipefail
# Before relying on restore, verify a snapshot with this exact name exists (exits non-zero if not)curl -sf "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/snapshots" \ -H "Authorization: Bearer $HOODY_TOKEN" \ | jq -e --arg n "production-stable" '.data.snapshots[] | select(.name == $n)'Encryption. Snapshots are stored on the server’s disk like the rest of the computer filesystem, so they are encrypted at rest with it: a snapshot on a stolen or seized drive is ciphertext. That protection does not cover a running server, and it does not follow a snapshot copied elsewhere. For sensitive data, encrypt at the application level before snapshotting.
Suggested expiry
Section titled “Suggested expiry”{ "alias": "before-experiment", "expiry": 7}Short experiments: 7 days, then automatic cleanup
{ "alias": "pre-deploy-v2.1.0", "expiry": 30}After deployment verified (30 days): Auto-delete
{ "alias": "v1.0.0-stable"}Major versions: Omit expiry to keep permanently
# Expires in 30 daysPOST /api/v1/computers/{id}/snapshots{"alias": "temp-backup", "expiry": 30}
# Expires in 90 daysPOST /api/v1/computers/{id}/snapshots{"alias": "quarterly-backup", "expiry": 90}
# Never expires (omit the `expiry` field entirely)POST /api/v1/computers/{id}/snapshots{"alias": "permanent-baseline"}Recipes
Section titled “Recipes”Snapshot before every risky change
Section titled “Snapshot before every risky change”Take a snapshot before every change you might want to undo. If anything breaks, restore the snapshot you took just before the change.
# Before AI code generationPOST /api/v1/computers/{id}/snapshots{"alias": "before-ai-gen-${timestamp}"}
# Before manual configurationPOST /api/v1/computers/{id}/snapshots{"alias": "before-nginx-config"}
# Before dependency updatesPOST /api/v1/computers/{id}/snapshots{"alias": "before-npm-update"}The same for a deployment:
# Production deployment in progressPOST /api/v1/computers/{prod_id}/snapshots{"alias": "pre-deploy-2025-11-09-14-30"}
# Deploy...
# Issues in production? First keep the current state:# a restore discards everything written since the snapshotPOST /api/v1/computers/{prod_id}/snapshots{"alias": "before-rollback-2025-11-09-15-10"}
# Then restore by the snapshot's `name`# (for this alias-created snapshot the name IS the alias; use the exact `name` returned by create/list)PUT /api/v1/computers/{prod_id}/snapshots/{snapshot_name_from_create_or_list}
# Back to the pre-deploy state once the restore completesVersioned milestones
Section titled “Versioned milestones”Snapshot the states you may want to return to. Over time this gives the computer itself a version history.
# Working features (permanent, no expiry field)POST /api/v1/computers/{id}/snapshots{"alias": "v1.0.0-stable"}
# Before major refactorPOST /api/v1/computers/{id}/snapshots{"alias": "v1.0.0-before-refactor", "expiry": 90}
# After refactor complete (permanent, no expiry field)POST /api/v1/computers/{id}/snapshots{"alias": "v2.0.0-stable"}Branch points
Section titled “Branch points”Snapshots let you branch a computer the way Git branches a repository: keep a main line, take a snapshot before an experiment, then either promote the result or restore the main one.
# Main production statePOST /api/v1/computers/{prod_id}/snapshots{"alias": "prod-main"}
# Experiment: try a new featurePOST /api/v1/computers/{prod_id}/snapshots{"alias": "experiment-feature-x"}
# Work on feature...
# Feature works, so make it the new mainPOST /api/v1/computers/{prod_id}/snapshots{"alias": "prod-main-v2"}
# If the feature failed, restore the prod-main snapshot (by its `name`)PUT /api/v1/computers/{prod_id}/snapshots/{snapshot_name_from_create_or_list}Development checkpoints
Section titled “Development checkpoints”A 7-day expiry clears these checkpoints without any further action, once a list call shows that each one’s expires_at is not null. A null means that checkpoint is permanent and you delete it yourself.
# Working on complex feature over days# Create checkpoints at milestones
# Day 1: Database schema readyPOST /api/v1/computers/{dev_id}/snapshots{"alias": "checkpoint-db-schema", "expiry": 7}
# Day 2: API endpoints completePOST /api/v1/computers/{dev_id}/snapshots{"alias": "checkpoint-api-done", "expiry": 7}
# Day 3: Frontend integratedPOST /api/v1/computers/{dev_id}/snapshots{"alias": "checkpoint-frontend", "expiry": 7}
# If something breaks on day 4, restore the day 3 checkpoint# (use the exact `name` returned by create/list)PUT /api/v1/computers/{dev_id}/snapshots/{snapshot_name_from_create_or_list}Daily automated backups
Section titled “Daily automated backups”With expiry set, old snapshots delete themselves. Confirm expires_at is not null after creating: a null means that snapshot is permanent and you must delete it yourself. The expiry has to fit the cap: with one backup per day and a cap of 25, a 30-day expiry fills the computer after 25 backups. Subsequent creates return 400 COMPUTER_SNAPSHOT_LIMIT until a snapshot expires or is deleted. The script below reads snapshot_count and max_snapshots first and deletes the oldest daily backup when the computer is full. Have your scheduler report a thrown error, so a missed backup does not go unnoticed. For disaster recovery, also keep copies on another server (Copy & Sync).
// Automated snapshot script (run via cron)async function dailyBackup(computerId) { const token = process.env.HOODY_TOKEN; const date = new Date().toISOString().split('T')[0]; const base = `https://api.hoody.com/api/v1/computers/${computerId}/snapshots`; const auth = { 'Authorization': `Bearer ${token}` };
// Make room when the computer is at its snapshot cap const list = await fetch(base, { headers: auth }); if (!list.ok) throw new Error(`List failed: ${list.status}`); const { snapshots, snapshot_count, max_snapshots } = (await list.json()).data; // Today's backup already exists: nothing to do, and nothing to delete const alias = `daily-backup-${date}`; if (snapshots.some(s => s.name === alias || s.alias === alias)) return; if (max_snapshots !== null && snapshot_count >= max_snapshots) { const oldest = snapshots .filter(s => (s.alias ?? '').startsWith('daily-backup-')) .sort((a, b) => a.created_at.localeCompare(b.created_at))[0]; if (!oldest) throw new Error('Snapshot cap reached and no daily backup to delete'); const del = await fetch(`${base}/${oldest.name}`, { method: 'DELETE', headers: auth }); if (!del.ok) throw new Error(`Delete failed: ${del.status}`); }
const res = await fetch( `https://api.hoody.com/api/v1/computers/${computerId}/snapshots`, { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ alias, expiry: 30 // Up to 30 days, fewer when the cap is lower }) } ); if (!res.ok) throw new Error(`Backup failed: ${res.status}`);
// A successful create can leave expires_at null: that backup is permanent const after = await fetch(base, { headers: auth }); if (!after.ok) throw new Error(`List failed: ${after.status}`); const created = (await after.json()).data.snapshots .find(s => s.name === alias || s.alias === alias); if (!created) throw new Error(`Backup ${alias} not found after create: check the snapshot list`); if (created.expires_at === null) { throw new Error(`Backup ${alias} has no expiry: delete it yourself when it is no longer needed`); }
console.log(`Backup created: daily-backup-${date}`);}
// Run at 2 AM dailydailyBackup('890abcdef12345678901cdef');Clean up old snapshots
Section titled “Clean up old snapshots”The script deletes every expiring snapshot older than 30 days, before its own term, 90-day ones included. Setting expiry at creation avoids the script entirely, since the snapshots expire on their own (check expires_at is not null).
// Delete snapshots older than 30 days (except permanent ones)async function cleanupSnapshots(computerId) { const token = process.env.HOODY_TOKEN; const headers = { 'Authorization': `Bearer ${token}` };
// Get all snapshots const response = await fetch( `https://api.hoody.com/api/v1/computers/${computerId}/snapshots`, { headers } ); if (!response.ok) throw new Error(`List failed: ${response.status}`); const { snapshots } = await response.json().then(r => r.data);
// Find old, non-permanent snapshots const thirtyDaysAgo = Date.now() - (30 * 24 * 60 * 60 * 1000);
for (const snapshot of snapshots) { const createdTime = new Date(snapshot.created_at).getTime(); const isPermanent = snapshot.expires_at === null;
if (!isPermanent && createdTime < thirtyDaysAgo) { const res = await fetch( `https://api.hoody.com/api/v1/computers/${computerId}/snapshots/${snapshot.name}`, { method: 'DELETE', headers } ); if (!res.ok) throw new Error(`Delete of ${snapshot.name} failed: ${res.status}`); console.log(`Deleted old snapshot: ${snapshot.alias || snapshot.name}`); } }}Stop writes before snapshotting
Section titled “Stop writes before snapshotting”A filesystem with no writes in flight restores cleanly and consistently.
# Before snapshotting a computer with active databases/writes:
# 1. Stop computer (or flush/quiesce the workload)POST /api/v1/computers/{id}/stop
# 2. Create snapshot of a quiet, consistent filesystemPOST /api/v1/computers/{id}/snapshots{"alias": "daily-backup"}
# 3. Restart if neededPOST /api/v1/computers/{id}/startStaging from a production snapshot
Section titled “Staging from a production snapshot”A copy can read from a snapshot rather than the computer’s live disk. Staging then starts from the filesystem that snapshot captured. The copy still takes the source’s current environment variables.
# 1. Snapshot productionPOST /api/v1/computers/{prod_id}/snapshots{"alias": "prod-stable-2025-11-09"}
# 2. Copy to staging from this snapshotPOST /api/v1/computers/{prod_id}/copy{ "target_project_id": "{staging_project}", "name": "staging-env", "source_snapshot": "<snapshot-name-returned-by-create-or-list>"}Deploy with automatic rollback
Section titled “Deploy with automatic rollback”The rollback path lives inside the deploy function rather than in a runbook someone has to follow under pressure. The function stops before deploying if the pre-deploy snapshot was not created, keeps the current state before it restores, and never rolls back a healthy deploy because the later snapshot failed.
Pass your deployment function and a health-check function that accepts the computer ID and returns { ok: boolean }. If the restore call ends without an answer, or answers with a 5xx error, the result says rolledBack: 'unknown' with the snapshot name: check that the restore finished before you restore again.
async function deployWithSafety(computerId, deployScript, checkHealth) { const token = process.env.HOODY_TOKEN; const headers = { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }; const snapshotsUrl = `https://api.hoody.com/api/v1/computers/${computerId}/snapshots`; const createSnapshot = (alias, expiry) => fetch(snapshotsUrl, { method: 'POST', headers, body: JSON.stringify({ alias, expiry }) });
// 1. Pre-deploy snapshot; stop here if it was not created const snapshotRes = await createSnapshot(`pre-deploy-${Date.now()}`, 7); if (!snapshotRes.ok) throw new Error(`Pre-deploy snapshot failed: ${snapshotRes.status}`); const snapshot = await snapshotRes.json();
// 2. Execute deployment, then 3. health check let healthy = false; try { await deployScript(); healthy = (await checkHealth(computerId)).ok; } catch (error) { console.error('Deployment failed', error); }
if (!healthy) { // 4. Failure: keep the current state, then restore the pre-deploy snapshot const keepRes = await createSnapshot(`before-rollback-${Date.now()}`, 7); if (!keepRes.ok) throw new Error(`Snapshot before rollback failed: ${keepRes.status}; nothing restored`); const name = snapshot.data.snapshot.name; try { const restoreRes = await fetch(`${snapshotsUrl}/${name}`, { method: 'PUT', headers }); // A 5xx can arrive after the filesystem was replaced, so its outcome is unknown return { success: false, rolledBack: restoreRes.ok ? true : restoreRes.status >= 500 ? 'unknown' : false, snapshot: name }; } catch (error) { // The connection closed, but a large restore can still be running: // check that it finished before you restore again return { success: false, rolledBack: 'unknown', snapshot: name }; } }
// 5. Success: snapshot the deployed state. A failure here is reported, never rolled back const deployedRes = await createSnapshot(`deployed-${Date.now()}`, 30).catch(() => null); return { success: true, deployedSnapshot: Boolean(deployedRes && deployedRes.ok) };}