Skip to main content
Snapshots capture the full state of a running VM, including memory, disk, and CPU state. Snapshots are stored in S3-compatible storage and can be used to quickly restore VMs to a previous state.
Snapshot functionality requires S3 configuration. Set the HATCH_S3_BUCKET, HATCH_S3_ENDPOINT, HATCH_S3_ACCESS_KEY, and HATCH_S3_SECRET_KEY environment variables.

​
Create Snapshot

Create a snapshot of a running VM. The VM’s memory, disk, and CPU state are captured and uploaded to S3 storage.

​
Path Parameters

​
id
string
required
The VM ID to snapshot.

​
Response

​
id
string
Unique snapshot identifier (e.g., snap_abc123).
​
vm_id
string
The ID of the VM that was snapshotted.
​
state_key
string
S3 key for the VM state file.
​
memory_key
string
S3 key for the memory snapshot file.
​
disk_key
string
S3 key for the disk snapshot file.
​
vm_config
string
JSON-encoded VM configuration at the time of snapshot.
​
size_bytes
integer
Total size of the snapshot in bytes.
​
created_at
string
ISO 8601 timestamp when the snapshot was created.

​
Example Request

curl -X POST http://localhost:8080/vms/vm_abc123def456/snapshot \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example Response

{
  "id": "snap_xyz789ghi012",
  "vm_id": "vm_abc123def456",
  "state_key": "snapshots/vm_abc123def456/snap_xyz789ghi012/vmstate",
  "memory_key": "snapshots/vm_abc123def456/snap_xyz789ghi012/memory",
  "disk_key": "snapshots/vm_abc123def456/snap_xyz789ghi012/disk",
  "vm_config": "{\"vcpu_count\":2,\"mem_mib\":1024}",
  "size_bytes": 1073741824,
  "created_at": "2026-03-06T12:30:00Z"
}

​
Restore Snapshot

Restore a VM from its most recent snapshot. The VM must be in a snapshotted state. This operation downloads the snapshot files from S3 and restarts the VM with the restored state.

​
Path Parameters

​
id
string
required
The VM ID to restore.

​
Response

Returns the restored VM object with state set to running.
​
id
string
The VM ID.
​
image_id
string
The image ID used for this VM.
​
state
string
VM state after restoration (typically running).
​
vcpu_count
integer
Number of virtual CPUs.
​
mem_mib
integer
Memory size in MiB.
​
guest_ip
string
The guest IP address.
​
guest_mac
string
The guest MAC address.
​
tap_name
string
The TAP network interface name.
​
ssh_port
integer
The host port forwarded to the VM’s SSH port.
​
enable_network
boolean
Whether networking is enabled.
​
created_at
string
Original VM creation timestamp.
​
updated_at
string
Timestamp when the VM was last updated (restore time).

​
Example Request

curl -X POST http://localhost:8080/vms/vm_abc123def456/restore \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example Response

{
  "id": "vm_abc123def456",
  "image_id": "img_default",
  "state": "running",
  "vcpu_count": 2,
  "mem_mib": 1024,
  "guest_ip": "172.16.0.10",
  "guest_mac": "02:FC:00:00:00:0A",
  "tap_name": "tap0",
  "ssh_port": 16001,
  "enable_network": true,
  "created_at": "2026-03-06T12:00:00Z",
  "updated_at": "2026-03-06T12:35:00Z"
}

​
List Snapshots

Retrieve all snapshots for a specific VM.

​
Path Parameters

​
id
string
required
The VM ID.

​
Response

Returns an array of snapshot objects, ordered by creation date (most recent first).

​
Example Request

curl http://localhost:8080/vms/vm_abc123def456/snapshots \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example Response

[
  {
    "id": "snap_xyz789ghi012",
    "vm_id": "vm_abc123def456",
    "state_key": "snapshots/vm_abc123def456/snap_xyz789ghi012/vmstate",
    "memory_key": "snapshots/vm_abc123def456/snap_xyz789ghi012/memory",
    "disk_key": "snapshots/vm_abc123def456/snap_xyz789ghi012/disk",
    "vm_config": "{\"vcpu_count\":2,\"mem_mib\":1024}",
    "size_bytes": 1073741824,
    "created_at": "2026-03-06T12:30:00Z"
  },
  {
    "id": "snap_abc123def456",
    "vm_id": "vm_abc123def456",
    "state_key": "snapshots/vm_abc123def456/snap_abc123def456/vmstate",
    "memory_key": "snapshots/vm_abc123def456/snap_abc123def456/memory",
    "disk_key": "snapshots/vm_abc123def456/snap_abc123def456/disk",
    "vm_config": "{\"vcpu_count\":2,\"mem_mib\":1024}",
    "size_bytes": 1073741824,
    "created_at": "2026-03-06T12:00:00Z"
  }
]

​
Snapshot Workflow

1

Create a running VM

Use the Create VM endpoint to start a new VM.
2

Create a snapshot

When the VM is in a desired state, create a snapshot. The VM state is snapshotted after this operation.
3

Restore when needed

Use the restore endpoint to return the VM to the snapshotted state.
Restoring a snapshot will replace the current VM state entirely. Any changes made since the snapshot was created will be lost.

Build docs developers (and LLMs) love

Get started for freeTalk to us