# Snapshots reference **Page:** foundation/computers/snapshots/reference [Download Raw Markdown](./foundation/computers/snapshots/reference.md) --- # Snapshots reference Lookup tables for [snapshots](/foundation/computers/snapshots/). Every field and status code is in the [Computer Snapshots API](/api/computer-snapshots/). ## 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}`](/api/computers/) | `hoody computers get` | `client.api.computers.get(id)` | | Copy a computer, optionally from a specific snapshot | [`POST /api/v1/computers/{id}/copy`](/api/computer-copy-sync/) 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 | 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](/foundation/hoody-api/authentication/#automation-and-ai-agents-recommended)). ## 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. ```bash # 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 | 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](#limits)) | The create call returns as soon as the snapshot exists, whether the computer is running or stopped. **Response:** ```json { "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:** ```json { "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 | 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](/foundation/servers/paid-subservers/); 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](/foundation/pricing/#what-does-each-limit-count); delete snapshots you no longer need. ## 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](#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: ```bash # Works whether the computer is running or stopped curl -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 | | 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](/foundation/computers/copy-sync/) for duplication workflows. ```bash # Create computer from specific snapshot POST /api/v1/computers/{source_id}/copy { "target_project_id": "{project_id}", "name": "restored-copy", "source_snapshot": "snap-20251109-143045" } ``` ## 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](#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](#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](#limits). 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 | 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](#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](#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 **Snapshot before destructive filesystem changes**, such as force-stopping a computer ([Managing Computers](/foundation/computers/managing/)), dependency updates, database migrations, deployments or a change of base software ([Images](/foundation/computers/images/)). A snapshot holds the filesystem only. Restoring it does not roll back [network](/foundation/networking/network/) or [firewall](/foundation/networking/firewall/) settings, so note those before you change them: ```bash # 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](/foundation/computers/copy-sync/), 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: ```bash 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 ```json { "alias": "before-experiment", "expiry": 7 } ``` **Short experiments:** 7 days, then automatic cleanup ```json { "alias": "pre-deploy-v2.1.0", "expiry": 30 } ``` **After deployment verified (30 days):** Auto-delete ```json { "alias": "v1.0.0-stable" } ``` **Major versions:** Omit `expiry` to keep permanently ```bash # Expires in 30 days POST /api/v1/computers/{id}/snapshots {"alias": "temp-backup", "expiry": 30} # Expires in 90 days POST /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 ### 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. ```bash # Before AI code generation POST /api/v1/computers/{id}/snapshots {"alias": "before-ai-gen-${timestamp}"} # Before manual configuration POST /api/v1/computers/{id}/snapshots {"alias": "before-nginx-config"} # Before dependency updates POST /api/v1/computers/{id}/snapshots {"alias": "before-npm-update"} ``` The same for a deployment: ```bash # Production deployment in progress POST /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 snapshot POST /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 completes ``` ### Versioned milestones Snapshot the states you may want to return to. Over time this gives the computer itself a version history. ```bash # Working features (permanent, no expiry field) POST /api/v1/computers/{id}/snapshots {"alias": "v1.0.0-stable"} # Before major refactor POST /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 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. ```bash # Main production state POST /api/v1/computers/{prod_id}/snapshots {"alias": "prod-main"} # Experiment: try a new feature POST /api/v1/computers/{prod_id}/snapshots {"alias": "experiment-feature-x"} # Work on feature... # Feature works, so make it the new main POST /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 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. ```bash # Working on complex feature over days # Create checkpoints at milestones # Day 1: Database schema ready POST /api/v1/computers/{dev_id}/snapshots {"alias": "checkpoint-db-schema", "expiry": 7} # Day 2: API endpoints complete POST /api/v1/computers/{dev_id}/snapshots {"alias": "checkpoint-api-done", "expiry": 7} # Day 3: Frontend integrated POST /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 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](#limits): 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](/foundation/computers/copy-sync/)). ```javascript // 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 daily dailyBackup('890abcdef12345678901cdef'); ``` ### 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`). ```javascript // 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 A filesystem with no writes in flight restores cleanly and consistently. ```bash # 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 filesystem POST /api/v1/computers/{id}/snapshots {"alias": "daily-backup"} # 3. Restart if needed POST /api/v1/computers/{id}/start ``` ### 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. ```bash # 1. Snapshot production POST /api/v1/computers/{prod_id}/snapshots {"alias": "prod-stable-2025-11-09"} # 2. Copy to staging from this snapshot POST /api/v1/computers/{prod_id}/copy { "target_project_id": "{staging_project}", "name": "staging-env", "source_snapshot": "" } ``` ### 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](#troubleshooting) before you restore again. ```javascript 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) }; } ```