Snapshots

Snapshots are time travel for containers. Capture complete state at any moment, restore instantly, branch your computers like Git branches code.

After creating and managing containers, you need protection against mistakes and the ability to version your infrastructure.

---

API Endpoints Summary

Official Technical Reference:

This Foundation page explains snapshot concepts and workflows. For complete endpoint documentation:

Snapshot Operations:

• GET /api/v1/containers/{id}/snapshots - List all snapshots
• POST /api/v1/containers/{id}/snapshots - Create new snapshot
• PUT /api/v1/containers/{id}/snapshots/{name} - Restore from snapshot
• DELETE /api/v1/containers/{id}/snapshots/{name} - Delete snapshot
• PUT /api/v1/containers/{id}/snapshots/{name}/alias - Update snapshot alias

Related:

• GET /api/v1/containers/{id} - Container details
• POST /api/v1/containers/{id}/copy - Copy a container (optionally from a specific snapshot)

---

Prerequisite — $HOODY_TOKEN. The HTTP examples on this page assume HOODY_TOKEN is exported to a valid Hoody bearer token. Create a long-lived automation token (hdy_…) via the token flow, then export HOODY_TOKEN=hdy_… before running the curl snippets.

What Are Snapshots?

A snapshot captures the complete state of a container at a specific moment:

Yesterday ──→ 3 hours ago ──→ 1 hour ago ──→ NOW
    ●              ●               ●            ●

Each point = a snapshot. Restore to any moment. Everything on disk returns:

• Entire filesystem (all files, exactly as they were)
• Database files (data at that moment, as written to disk)
• Configuration (config files, environment files written to disk)
• Installed software (packages, dependencies)

Note

Snapshots are filesystem-only (stateless). They capture the container’s disk at a point in time — not RAM, not running processes, and not in-flight network connections. To guarantee a clean on-disk state for databases or apps holding data in memory, flush/stop them (or stop the container) before snapshotting.

Think of it as: Git for entire computers, not just code.

Powered by Copy-on-Write (CoW):

• Instant creation - No need to copy entire filesystem
• Space efficient - Only changed blocks are stored after snapshot
• Fast restoration - CoW enables rapid rollback to any point
• Cheap snapshots - Minimal storage overhead per snapshot

Tip

In the AI era, snapshots are survival. When AI generates code you can’t review, snapshot before execution. If it breaks something, instant rollback. Experimentation becomes safe.

---

Why Snapshots Matter

The AI Safety Net

From Understanding Hoody:

Snapshot before AI rewrites code. Instant rollback if it breaks.
Snapshot before deployments. Restore everything in seconds.
Snapshot experiments. Branch computers like Git branches code.

Time travel makes experimentation weightless — nothing you try is ever final.

Real-World Protection

Before risky changes:

POST Create a snapshot before AI refactor

/api/v1/containers/{container_id}/snapshots

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

If something breaks, restore the snapshot:

PUT Restore from snapshot

/api/v1/containers/{container_id}/snapshots/{snapshot_name}

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Before deployments:

# Production deployment in progress
POST /api/v1/containers/{prod_id}/snapshots
{"alias": "pre-deploy-2025-11-09-14-30"}

# Deploy...

# Issues in production? Restore by the snapshot's `name`
# (the sanitized alias supplied at creation is that name)
PUT /api/v1/containers/{prod_id}/snapshots/pre-deploy-2025-11-09-14-30

# Back to working state instantly

---

Creating Snapshots

Basic Snapshot Creation

POST Create a new snapshot

/api/v1/containers/{container_id}/snapshots

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Response:

{
  "statusCode": 200,
  "message": "Snapshot created successfully",
  "data": {
    "container_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
    }
  }
}

Snapshot created instantly. Works while the container is running or stopped.

Snapshot Naming

Auto-generated names (no alias sent at creation):

• Format: snap-YYYYMMDD-HHMMSS
• Example: snap-20251109-143045
• Unique, chronologically sortable

Aliases sent at creation become the name:

• The alias you pass to the create call is sanitized to [a-zA-Z0-9_-] (leading dashes removed) and used as the snapshot’s name — "My Backup" lands as MyBackup
• An alias that sanitizes to an empty string falls back to the timestamp form
• Max 100 characters
• Example: "pre-deploy", "working-state", "before-ai-changes"
• Setting an alias later (alias update) does not rename the snapshot — the name stays whatever it was at creation

Always take the restore/delete key from the name field returned by the list call.

Snapshot Expiration

Snapshots can auto-delete after specified days:

# Expires in 30 days
POST /api/v1/containers/{id}/snapshots
{"alias": "temp-backup", "expiry": 30}

# Expires in 90 days
POST /api/v1/containers/{id}/snapshots
{"alias": "quarterly-backup", "expiry": 90}

# Never expires (omit the `expiry` field entirely)
POST /api/v1/containers/{id}/snapshots
{"alias": "permanent-baseline"}

After expiration:

• Snapshot auto-deleted
• Storage freed
• Cannot be restored

Use expiration for:

• Temporary experiment backups
• Pre-deployment snapshots (delete after verification)
• Automated cleanup of old backups

---

Restoring Snapshots

Revert container to any previous snapshot.

Basic Restore

PUT Restore container from snapshot

/api/v1/containers/{container_id}/snapshots/{snapshot_name}

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

What happens:

1. Current container filesystem is discarded
2. Snapshot’s filesystem is applied
3. Container filesystem reverts to the snapshot
4. On-disk configuration reverts to the snapshot
5. Container starts fresh from the restored filesystem (processes do not resume mid-execution)

Restoration time: Depends on snapshot size and how much the disk has changed since — small restores finish in seconds, very large ones can take many minutes.

Caution

Restoration is destructive. Current container state is lost. If you want to preserve current state, snapshot it first before restoring.

Safe Restore Workflow

1. Snapshot Current State

# Capture "right now" before restoring
curl -X POST "https://api.hoody.icu/api/v1/containers/{id}/snapshots" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"alias": "before-restore"}'

Now you can restore to EITHER state.

2. Restore to Desired State

# Restore to previous snapshot (use the exact `name` returned by create/list)
curl -X PUT "https://api.hoody.icu/api/v1/containers/{id}/snapshots/{snapshot_name_from_list}" \
  -H "Authorization: Bearer $HOODY_TOKEN"

3. Verify Restoration

# Check container status
curl "https://api.hoody.icu/api/v1/containers/{id}" \
  -H "Authorization: Bearer $HOODY_TOKEN"

# Confirm status == "running" (or whatever state matches the snapshot)

4. Test Application

# Access via service URLs
# https://{project}-{container}-terminal-1.{server}.containers.hoody.icu

# Verify everything works as expected
# If issues, restore to "before-restore" snapshot

---

Listing Snapshots

View all snapshots for a container:

GET List all snapshots for a container

/api/v1/containers/{container_id}/snapshots

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Response:

{
  "statusCode": 200,
  "message": "Snapshots retrieved successfully",
  "data": {
    "container_id": "890abcdef12345678901cdef",
    "project_id": "67e89abc123def456789abcd",
    "snapshots": [
      {
        "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
      },
      {
        "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
      }
    ]
  }
}

Key information:

• name - The restore/delete key: the sanitized alias supplied at creation, or an auto-generated snap-YYYYMMDD-HHMMSS when no alias was supplied. In the two examples above, the creation aliases became their names.
• alias - Your friendly name; can be set or changed later without renaming the snapshot
• created_at - When snapshot was taken
• last_used_at - When last used for restore/copy (null if never used)
• 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)

---

What Snapshots Capture

Snapshots are stateless (filesystem-only):

# Works whether the container is running or stopped
POST /api/v1/containers/{id}/snapshots

Includes:

• Filesystem (everything written to disk)

Does not include:

• Running processes
• RAM / memory state
• In-flight network connections

The stateful field on every snapshot is false — Hoody snapshots do not capture a RAM dump.

Restoration: The container’s filesystem reverts to the snapshot, then the container starts fresh from that disk state. Processes do not resume mid-execution; anything that was only in memory at snapshot time is not restored.

Tip

Snapshotting a running container is safe, but apps holding important data in memory (databases, queues) should flush to disk — or be stopped — first, so the captured filesystem is consistent.

---

Deleting Snapshots

Permanently remove snapshots to free storage:

DELETE Delete a snapshot

/api/v1/containers/{container_id}/snapshots/{snapshot_name}

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

What gets deleted:

• Snapshot data (the captured filesystem state)
• Snapshot metadata (alias, timestamps)
• Storage space freed

Cannot be recovered. The snapshot reference name becomes invalid.

When to Delete Snapshots

Delete snapshots when:

• Expired temporary backups
• Superseded by newer snapshots
• Storage optimization needed
• Old experiment branches no longer needed

Keep snapshots when:

• Long-term disaster recovery
• Compliance/audit requirements
• Template for new containers (copy from snapshot)
• Historical reference (architecture decisions, configurations)

---

Snapshot Strategies

Strategy 1: Pre-Operation Safety

Snapshot before every risky change:

# Before AI code generation
POST /api/v1/containers/{id}/snapshots
{"alias": "before-ai-gen-${timestamp}"}

# Before manual configuration
POST /api/v1/containers/{id}/snapshots
{"alias": "before-nginx-config"}

# Before dependency updates
POST /api/v1/containers/{id}/snapshots
{"alias": "before-npm-update"}

If anything breaks: Restore in seconds.

Strategy 2: Versioned Milestones

Snapshot significant states:

# Working features (permanent — no expiry field)
POST /api/v1/containers/{id}/snapshots
{"alias": "v1.0.0-stable"}

# Before major refactor
POST /api/v1/containers/{id}/snapshots
{"alias": "v1.0.0-before-refactor", "expiry": 90}

# After refactor complete (permanent — no expiry field)
POST /api/v1/containers/{id}/snapshots
{"alias": "v2.0.0-stable"}

Create version history for your infrastructure.

Strategy 3: Daily Automated Backups

// Automated snapshot script (run via cron)
async function dailyBackup(containerId) {
  const token = process.env.HOODY_TOKEN;
  const date = new Date().toISOString().split('T')[0];

  await fetch(
    `https://api.hoody.icu/api/v1/containers/${containerId}/snapshots`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        alias: `daily-backup-${date}`,
        expiry: 30  // Keep 30 days of dailies
      })
    }
  );

  console.log(`Backup created: daily-backup-${date}`);
}

// Run at 2 AM daily
dailyBackup('890abcdef12345678901cdef');

Combine with expiry: Old snapshots auto-delete, no manual cleanup needed.

Strategy 4: Git-Style Branching

Branch your infrastructure like Git:

# Main production state
POST /api/v1/containers/{prod_id}/snapshots
{"alias": "prod-main"}

# Experiment: Try new feature
POST /api/v1/containers/{prod_id}/snapshots
{"alias": "experiment-feature-x"}

# Work on feature...

# Feature works! Merge by making it the new main
POST /api/v1/containers/{prod_id}/snapshots
{"alias": "prod-main-v2"}

# Or feature failed? Restore to the prod-main snapshot (by its `name`)
PUT /api/v1/containers/{prod_id}/snapshots/prod-main

Same container, multiple timelines.

---

Snapshot Operations

List All Snapshots

GET List all snapshots

/api/v1/containers/{container_id}/snapshots

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Returns chronological list with details for each snapshot.

Create Snapshot

POST Create a new snapshot

/api/v1/containers/{container_id}/snapshots

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Both parameters optional:

• No alias → Only auto-generated name
• No expiry → Permanent snapshot

Restore Snapshot

PUT Restore from snapshot

/api/v1/containers/{container_id}/snapshots/{snapshot_name}

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Use the snapshot’s name, as returned by GET /api/v1/containers/{id}/snapshots. Create a snapshot without an alias and the name is auto-generated as snap-YYYYMMDD-HHMMSS. Pass an alias at creation and that alias — stripped to [a-zA-Z0-9_-], with leading dashes removed — becomes the name (an alias that sanitizes to nothing falls back to the timestamp form). Never assume the format: list the snapshots first and pass the exact name field to the restore call.

Delete Snapshot

DELETE Delete a snapshot

/api/v1/containers/{container_id}/snapshots/{snapshot_name}

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Storage freed immediately.

---

Snapshot Size & Storage

Snapshots consume storage based on container size:

Container Disk Usage	First Snapshot Size
10 GB filesystem	~10 GB
50 GB filesystem	~50 GB
100 GB filesystem	~100 GB

Snapshots are filesystem-only, so the first snapshot tracks the container’s on-disk usage (no RAM dump is stored). Subsequent snapshots are incremental — only changed blocks are stored, so they cost far less than a full copy.

Incremental snapshots:

• First snapshot: Full size
• Subsequent snapshots: Only changes (incremental)
• Hoody optimizes storage automatically

Storage costs apply. Delete old snapshots to minimize expense.

---

Snapshots vs Container Copy

Snapshots

Purpose: Time travel within container

Characteristics:

• Instant creation (seconds)
• Incremental storage
• Built into container
• Fast restoration
• Tied to source container
• Can’t run independently
• Deleted with the container (cascade delete)

Use for:

• Backup/restore
• Experimenting safely
• Rollback mechanism
• Version milestones

Container Copy

Purpose: Duplicate entire container

Characteristics:

• Independent container
• Can run on different server
• Can be in different project
• Survives source deletion
• Slower creation (minutes)
• Full storage (no incremental)
• More resources required

Use for:

• Creating staging from prod
• Disaster recovery (different server)
• Team environments (same setup)
• Production redundancy

You can copy FROM snapshots:

# Create container from specific snapshot
POST /api/v1/containers/{source_id}/copy
{
  "target_project_id": "{project_id}",
  "name": "restored-copy",
  "source_snapshot": "snap-20251109-143045"
}

See: Copy & Sync for duplication workflows.

---

Real-World Scenarios

Scenario 1: Safe AI Experimentation

CLI

# 1. Snapshot current working state
hoody snapshots create --container $DEV_ID --alias "working-baseline"

# 2. Let AI agent make changes...

# 3. Changes work? Create new milestone
hoody snapshots create --container $DEV_ID --alias "with-ai-improvements"

# Or changes broke something? Restore baseline
# (use the exact `name` returned by create/list; when supplied at creation,
#  the sanitized alias is that name)
# `-y` skips the destructive-operation confirmation prompt — required in scripts and agents
hoody snapshots restore --container $DEV_ID --name working-baseline -y

SDK

// 1. Snapshot current working state
await client.api.containers.createSnapshot(DEV_ID, { alias: 'working-baseline' });

// 2. Let AI agent make changes...

// 3. Changes work? Create new milestone
await client.api.containers.createSnapshot(DEV_ID, { alias: 'with-ai-improvements' });

// Or changes broke something? Restore baseline
// (use the exact `name` returned by create/list; when supplied at creation,
//  the sanitized alias is that name)
await client.api.containers.restoreSnapshot(DEV_ID, 'working-baseline');

HTTP

# 1. Snapshot current working state
curl -X POST "https://api.hoody.icu/api/v1/containers/{dev_id}/snapshots" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"alias": "working-baseline"}'

# 2. Let AI agent make changes...

# 3. Changes work? Create new milestone
curl -X POST "https://api.hoody.icu/api/v1/containers/{dev_id}/snapshots" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"alias": "with-ai-improvements"}'

# Or changes broke something? Restore baseline
# (use the exact `name` returned by create/list; when supplied at creation,
#  the sanitized alias is that name)
curl -X PUT "https://api.hoody.icu/api/v1/containers/{dev_id}/snapshots/working-baseline" \
  -H "Authorization: Bearer $HOODY_TOKEN"

AI can break things freely. You always have a way back.

Scenario 2: Production Deployment with Rollback

CLI

# Before deployment
hoody snapshots create --container $PROD_ID \
  --alias "pre-deploy-v2.1.0" --expiry 30

# Deploy via terminal/SSH...

# Issue detected! Rollback (use the exact `name` returned by create/list; when
# supplied at creation, the sanitized alias is that name — the dots are stripped,
# so "pre-deploy-v2.1.0" lands as "pre-deploy-v210")
# `-y` skips the destructive-operation confirmation prompt — required in scripts and agents
hoody snapshots restore --container $PROD_ID --name pre-deploy-v210 -y

# Production rolled back to the snapshot state

SDK

// Before deployment
await client.api.containers.createSnapshot(PROD_ID, { alias: 'pre-deploy-v2.1.0', expiry: 30 });

// Deploy via terminal...

// Issue detected! Rollback (use the exact `name` returned by create/list; when
// supplied at creation, the sanitized alias is that name — the dots are stripped,
// so 'pre-deploy-v2.1.0' lands as 'pre-deploy-v210')
await client.api.containers.restoreSnapshot(PROD_ID, 'pre-deploy-v210');
// Production restored in 15 seconds

HTTP

# Before deployment
curl -X POST "https://api.hoody.icu/api/v1/containers/{prod_id}/snapshots" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"alias": "pre-deploy-v2.1.0", "expiry": 30}'

# Deploy via terminal/SSH
# https://{project}-{prod_id}-terminal-1.{server}.containers.hoody.icu

# Issue detected! Rollback (use the exact `name` returned by create/list; when
# supplied at creation, the sanitized alias is that name — the dots are stripped,
# so "pre-deploy-v2.1.0" lands as "pre-deploy-v210")
curl -X PUT "https://api.hoody.icu/api/v1/containers/{prod_id}/snapshots/pre-deploy-v210" \
  -H "Authorization: Bearer $HOODY_TOKEN"

# Production restored in 15 seconds

Scenario 3: Development Checkpoints

# Working on complex feature over days
# Create checkpoints at milestones

# Day 1: Database schema ready
POST /api/v1/containers/{dev_id}/snapshots
{"alias": "checkpoint-db-schema", "expiry": 7}

# Day 2: API endpoints complete
POST /api/v1/containers/{dev_id}/snapshots
{"alias": "checkpoint-api-done", "expiry": 7}

# Day 3: Frontend integrated
POST /api/v1/containers/{dev_id}/snapshots
{"alias": "checkpoint-frontend", "expiry": 7}

# Something breaks on Day 4?
# Restore to Day 3 checkpoint (use the exact `name` returned by create/list;
# when supplied at creation, the sanitized alias is that name)
PUT /api/v1/containers/{dev_id}/snapshots/checkpoint-frontend

Time-limited snapshots: 7-day expiry means automatic cleanup.

Scenario 4: Container Templates

CLI

# Snapshot as permanent template
hoody snapshots create --container $TEMPLATE_ID \
  --alias "dev-template-2025"

# New developer joins? Copy from this snapshot
hoody containers copy $TEMPLATE_ID \
  --target-project-id $THEIR_PROJECT \
  --name "new-dev-env" \
  --source-snapshot "dev-template-2025"

SDK

// Snapshot as permanent template (omit `expiry` for no expiration)
await client.api.containers.createSnapshot(TEMPLATE_ID, { alias: 'dev-template-2025' });

// New developer joins? Copy from this snapshot
await client.api.containers.copy(TEMPLATE_ID, {
  target_project_id: THEIR_PROJECT,
  name: 'new-dev-env',
  source_snapshot: 'dev-template-2025'
});

HTTP

# Snapshot as permanent template
curl -X POST "https://api.hoody.icu/api/v1/containers/{template_id}/snapshots" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"alias": "dev-template-2025"}'

# New developer joins? Copy from this snapshot
curl -X POST "https://api.hoody.icu/api/v1/containers/{template_id}/copy" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_project_id": "{their_project}",
    "name": "new-dev-env",
    "source_snapshot": "dev-template-2025"
  }'

One perfect setup, infinite duplicates.

---

Snapshot Management

List Snapshots

GET List all snapshots for a container

/api/v1/containers/{container_id}/snapshots

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Use the returned list to:

• Monitor snapshot accumulation (response.data.snapshots.length)
• Trigger cleanup when count is high
• Verify a specific snapshot exists before restore

Cleanup Old Snapshots

// Delete snapshots older than 30 days (except permanent ones)
async function cleanupSnapshots(containerId) {
  const token = process.env.HOODY_TOKEN;
  const headers = { 'Authorization': `Bearer ${token}` };

  // Get all snapshots
  const response = await fetch(
    `https://api.hoody.icu/api/v1/containers/${containerId}/snapshots`,
    { headers }
  );
  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) {
      await fetch(
        `https://api.hoody.icu/api/v1/containers/${containerId}/snapshots/${snapshot.name}`,
        { method: 'DELETE', headers }
      );
      console.log(`Deleted old snapshot: ${snapshot.alias || snapshot.name}`);
    }
  }
}

Or use expiry parameter: Snapshots delete themselves automatically.

---

Snapshot Best Practices

1. Snapshot Before Destructive Operations

# Always snapshot before:
POST /api/v1/containers/{id}/snapshots

# Then:
- force-stop operations
- major configuration changes
- dependency updates (npm, apt, pip)
- database migrations
- letting AI modify code
- production deployments

2. Use Descriptive Aliases

# 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"}

Future you will thank present you.

3. Set Appropriate Expiration

Temporary Safety

{
  "alias": "before-experiment",
  "expiry": 7
}

Short experiments: 7 days auto-cleanup

Deployment Backups

{
  "alias": "pre-deploy-v2.1.0",
  "expiry": 30
}

After deployment verified (30 days): Auto-delete

Milestone Versions

{
  "alias": "v1.0.0-stable"
}

Major versions: Omit expiry to keep permanently

4. Stop (or Quiesce) Before Snapshotting for Consistency

# Before snapshotting a container with active databases/writes:

# 1. Stop container (or flush/quiesce the workload)
POST /api/v1/containers/{id}/stop

# 2. Create snapshot of a quiet, consistent filesystem
POST /api/v1/containers/{id}/snapshots
{"alias": "daily-backup"}

# 3. Restart if needed
POST /api/v1/containers/{id}/start

A quiet filesystem at snapshot time = a clean, consistent restore.

5. Verify Snapshots Exist

# Before relying on restore, verify snapshot exists
curl "https://api.hoody.icu/api/v1/containers/{id}/snapshots" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  | grep "production-stable"

Don’t assume old snapshots still exist (may have expired or been deleted).

---

Integration Patterns

With Container Copy

Use snapshots as copy sources:

# 1. Snapshot production
POST /api/v1/containers/{prod_id}/snapshots
{"alias": "prod-stable-2025-11-09"}

# 2. Copy to staging from this snapshot
POST /api/v1/containers/{prod_id}/copy
{
  "target_project_id": "{staging_project}",
  "name": "staging-env",
  "source_snapshot": "prod-stable-2025-11-09"
}

Staging gets exact production state from specific snapshot.

With Automated Deployment

async function deployWithSafety(containerId, deployScript) {
  const token = process.env.HOODY_TOKEN;
  const headers = { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' };

  // 1. Pre-deploy snapshot
  const snapshot = await fetch(
    `https://api.hoody.icu/api/v1/containers/${containerId}/snapshots`,
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        alias: `pre-deploy-${Date.now()}`,
        expiry: 7
      })
    }
  ).then(r => r.json());

  try {
    // 2. Execute deployment
    await deployScript();

    // 3. Health check
    const health = await checkHealth(containerId);

    if (!health.ok) {
      throw new Error('Health check failed');
    }

    // 4. Success - create "deployed" snapshot
    await fetch(
      `https://api.hoody.icu/api/v1/containers/${containerId}/snapshots`,
      {
        method: 'POST',
        headers,
        body: JSON.stringify({
          alias: `deployed-${Date.now()}`,
          expiry: 30
        })
      }
    );

    return { success: true };

  } catch (error) {
    // 5. Failure - restore snapshot
    console.error('Deployment failed, rolling back...', error);

    await fetch(
      `https://api.hoody.icu/api/v1/containers/${containerId}/snapshots/${snapshot.data.snapshot.name}`,
      { method: 'PUT', headers }
    );

    return { success: false, error, rolledBack: true };
  }
}

Deployment safety net built-in.

---

Useful Questions

How long does snapshot creation take?

Nearly instant — Copy-on-Write means only filesystem metadata is written, not a copy of your data. Your container keeps running during the snapshot — only the on-disk state is captured.

Can I snapshot a running container?

Yes! Snapshots work while the container is running or stopped — a paused container must be resumed or stopped first (the API rejects snapshotting a paused container). In every case the snapshot is filesystem-only — it captures the disk, not running processes or RAM. For the most consistent capture of in-memory data, flush or stop the workload first.

What happens to snapshots when I delete the container?

Snapshots are deleted with the container. Deleting a container permanently deletes all of its snapshots (cascade delete). If you want to keep the state, copy the container first — the copy becomes an independent container that survives its source.

Can I restore a snapshot to a different container?

Not directly via restore operation. But you can copy a container from a specific snapshot to create a new container with that snapshot’s state. Use source_snapshot parameter in copy operation.

How many snapshots can I create?

Each container has a snapshot cap enforced by the API — on free-tier servers it defaults to 10 per container, far higher on rented servers (both operator-tunable). Hitting the cap returns a clear error on the create call. Use expiry to automate cleanup and delete stale snapshots to stay under it.

Do snapshots include proxy aliases and permissions?

No. Snapshots capture container filesystem state only. Proxy aliases and permissions are configured separately at the proxy level. After restoring, you may need to reconfigure aliases.

Can I snapshot multiple containers simultaneously?

Yes — snapshot creation is a normal HTTP call per container, so you can script it across a fleet. Mind the account-wide write limit: snapshot create, restore, delete, and alias update share one bucket whose ceiling is SNAPSHOT_WRITE_RATE_LIMIT_MAX multiplied by the deployment’s RATE_LIMIT_MAX_MULTIPLIER — 50 requests per 5 minutes in the shipped configuration. Batch large fleets through a queue and retry on 429 rather than firing every request at once.

What’s the difference between snapshot and backup?

Snapshot is instant state capture. Backup is copying to external storage. Use snapshots for quick rollback (restore in seconds). Combine with container copy to different servers for true disaster recovery.

Can snapshots be encrypted?

Snapshots are stored on the server’s disk like the rest of the container filesystem, so they inherit the host’s LUKS full-disk encryption — a snapshot on a stolen or seized drive is ciphertext. That protection ends the moment the host is running and the volume is unlocked, and it does not follow a snapshot copied elsewhere. For sensitive data, encrypt at the application level before snapshotting.

---

Troubleshooting

Snapshot Creation Fails

Problem: Snapshot operation returns error

Solutions:

1. Check storage usage:

   GET /api/v1/containers/{id}
   # Verify container has available storage

2. Check container status:

   GET /api/v1/containers/{id}
   # status should be running or stopped, not failed/creating

3. Verify permissions:

   • Ensure you own the container
   • Check auth token is valid

Snapshot Restore Hangs

Problem: Restore operation doesn’t complete

Restore time varies widely with snapshot size and how far the disk has diverged

If longer:

1. Check snapshot size:

   GET /api/v1/containers/{id}/snapshots
   # Large snapshots (>100 GB) take longer

2. Wait longer for large snapshots — very large restores can take many minutes

3. Check server status:

   GET /api/v1/servers/{id}
   # Server status should be "active"

Cannot Find Snapshot to Restore

Problem: Restore returns 404 Not Found

Solutions:

1. Verify snapshot name (not alias):

   # List snapshots to get exact name
   GET /api/v1/containers/{id}/snapshots
   
   # Use the "name" field exactly as returned
   # It is the sanitized alias you passed at creation, or snap-YYYYMMDD-HHMMSS
   # if you created the snapshot without one — never guess the format

2. Check snapshot didn’t expire:

   GET /api/v1/containers/{id}/snapshots
   # Verify snapshot still in list
   # Check expires_at hasn't passed

Snapshots Consuming Too Much Storage

Problem: Snapshot storage costs are high

Solutions:

1. Delete old/unused snapshots:

   # List snapshots sorted by age
   GET /api/v1/containers/{id}/snapshots
   
   # Delete snapshots never used for restore
   DELETE /api/v1/containers/{id}/snapshots/{old_snapshot_name}

2. Set expiration on new snapshots:

   POST /api/v1/containers/{id}/snapshots
   {"alias": "temp-backup", "expiry": 7}

3. Trim the container filesystem before snapshotting (clear caches, logs, build artifacts) to reduce snapshot size:

   # e.g. clean package caches / temp files inside the container, then:
   POST /api/v1/containers/{id}/snapshots

Restored Container Different Than Expected

Problem: After restore, container state doesn’t match memory

Possible causes:

1. Restored wrong snapshot:

   • Verify the snapshot name/alias passed to the restore operation
   • Re-list snapshots and confirm the intended one was targeted

2. Snapshots are filesystem-only:

   • Running processes and in-memory state are never included
   • Only the filesystem is restored
   • Container starts fresh from that filesystem

3. Post-snapshot changes:

   • Snapshot only captures THAT moment
   • Changes after snapshot aren’t included
   • Verify snapshot created_at timestamp

---

What’s Next

Master container state management:

1. Copy & Sync → - Duplicate containers, sync changes
2. Images → - Choose base OS and software
3. Create, Edit, Delete → - Container fundamentals

Use snapshots with:

• Managing Containers → - Snapshot before stop/restart operations
• Network Configuration → - Snapshot before network changes
• Firewall → - Snapshot before firewall modifications

Understanding gained:

• Snapshots capture the container’s filesystem (stateless, no RAM/process state)
• Restore reverts the disk to any previous moment, then starts fresh
• Expiration enables automatic cleanup
• Snapshots are cascade-deleted with their container (copy the container first to preserve the state)
• Can copy containers from snapshots
• Incremental storage optimization

---

Snapshot before AI changes.
Snapshot before deployments.
Snapshot before experiments.
Instant rollback. Always safe. Time travel for computers.