Snapshots

Snapshots capture a machine’s environment — OS, architecture, runtime versions, dependencies, environment variables, and arbitrary metadata. Environment variables are encrypted at rest with AES-256-GCM.

Create a snapshot

POST /machine/snapshots

Roles: owner admin member

Request body

{
  "machineName": "james-mbp",
  "os": "darwin",
  "arch": "arm64",
  "runtimeVersions": {
    "node": "20.11.0",
    "python": "3.12.1"
  },
  "dependencies": {
    "package.json": { "hono": "^4.0.0", "typescript": "^5" }
  },
  "envVars": {
    "NODE_ENV": "development",
    "DATABASE_URL": "postgres://localhost:5432/mydb"
  },
  "metadata": { "shell": "zsh", "editor": "cursor" }
}

Field	Type	Required	Description
machineName	string	Yes	Identifier for the machine
os	string	No	Operating system (darwin, linux, win32)
arch	string	No	CPU architecture (arm64, x64)
runtimeVersions	object	No	Runtime name to version string
dependencies	object	No	Nested map: dependency file to packages
envVars	object	No	Key-value env vars (encrypted before storage)
metadata	object	No	Arbitrary metadata

Response 201

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "machineName": "james-mbp",
  "createdAt": "2026-02-07T12:00:00.000Z"
}

Returns 400 if machineName is missing. Returns 403 if the snapshot quota is exceeded.

List snapshots

GET /machine/snapshots

Returns snapshots for the current project. Env vars are not included in list responses.

Param	Type	Default	Description
limit	number	50	Max results (capped at 100)
offset	number	0	Pagination offset

Response

{
  "snapshots": [
    {
      "id": "a1b2c3d4-...",
      "machineName": "james-mbp",
      "os": "darwin",
      "arch": "arm64",
      "runtimeVersions": { "node": "20.11.0" },
      "metadata": { "shell": "zsh" },
      "createdAt": "2026-02-07T12:00:00.000Z"
    }
  ]
}

Get a snapshot

GET /machine/snapshots/:id

Returns a single snapshot with decrypted environment variables.

{
  "id": "a1b2c3d4-...",
  "machineName": "james-mbp",
  "os": "darwin",
  "arch": "arm64",
  "runtimeVersions": { "node": "20.11.0", "python": "3.12.1" },
  "dependencies": { "package.json": { "hono": "^4.0.0" } },
  "envVars": { "NODE_ENV": "development", "DATABASE_URL": "postgres://..." },
  "metadata": { "shell": "zsh" },
  "createdAt": "2026-02-07T12:00:00.000Z"
}

Returns 404 if the snapshot doesn’t exist in this project.

Delete a snapshot

DELETE /machine/snapshots/:id

Roles: owner admin member

Permanently deletes a snapshot. Triggers the snapshot.deleted webhook event.

Returns { "success": true } on success, 404 if not found.

Compare two snapshots

POST /machine/snapshots/compare

Compares two snapshots and returns a structured diff.

Request body

{
  "snapshotA": "uuid-1",
  "snapshotB": "uuid-2",
  "includeEnvValues": false
}

Field	Type	Required	Description
snapshotA	string	Yes	UUID of the first snapshot
snapshotB	string	Yes	UUID of the second snapshot
includeEnvValues	boolean	No	Include env var key comparison

Response

{
  "snapshotA": "uuid-1",
  "snapshotB": "uuid-2",
  "diff": {
    "os": { "a": "darwin", "b": "linux", "match": false },
    "arch": { "a": "arm64", "b": "x64", "match": false },
    "runtimes": [
      { "key": "node", "a": "20.11.0", "b": "18.19.0", "match": false }
    ],
    "dependencies": [
      { "key": "package.json/hono", "a": "^4.0.0", "b": "^4.0.0", "status": "same" },
      { "key": "package.json/lodash", "a": null, "b": "^4.17.0", "status": "added" }
    ],
    "envVars": [
      { "key": "NODE_ENV", "status": "same" },
      { "key": "SECRET_KEY", "status": "removed" }
    ]
  }
}

Dependency statuses: same, changed, added, removed. Env var statuses: same, added, removed.

Dependencies are flattened with / separators (e.g. package.json/hono).