Snapshots and Logs

Snapshots belong to environments. They are generation attempts, not ad hoc VM captures.

When an environment has a ready base snapshot, new VMs and sessions can boot from that prepared disk instead of rerunning setup from scratch. ready means a usable base snapshot exists; inspect base_snapshot.error to determine whether the latest rebuild succeeded. Failed setup attempts appear in the snapshots list; failures before snapshot creation or during capture may leave no snapshot row, so inspect environment logs too.

How Snapshot Generation Works

Snapshot generation boots a temporary VM from the environment manifest, clones sources, runs setup, starts and checks services as needed, captures the disk, and promotes the ready result to the environment's base snapshot.

Generation can start in a few ways:

• Create an environment with a manifest.
• Patch an environment's manifest.
• Explicitly regenerate with POST /v1/accounts/{account}/environments/{environment}/snapshots.
• Automatically, when Wallfacer refreshes an aged snapshot or rebuilds one that could not be restored. When an older ready snapshot exists, new VMs and sessions can still boot from it while the replacement generates. The API can report base_snapshot.status as generating or waiting during that work.

Explicit regeneration returns 202 Accepted; the work continues asynchronously.

A successful automatic refresh replaces the base snapshot. If it fails, the old snapshot remains bootable; inspect base_snapshot.error, snapshot attempts, and environment logs for failure details. Automatic refresh retries back off after a failure. An explicit regeneration can pause sessions while it runs.

curl -s -X POST "$WALLFACER_API/accounts/$ACCOUNT_ID/environments/$ENVIRONMENT_ID/snapshots" \
  -H "Authorization: Bearer $WALLFACER_TOKEN" \
  -H "Idempotency-Key: regenerate-env-001"

Poll The Environment

The environment record tells you the current base snapshot state.

curl -s "$WALLFACER_API/accounts/$ACCOUNT_ID/environments/$ENVIRONMENT_ID" \
  -H "Authorization: Bearer $WALLFACER_TOKEN" \
  | jq ".data.base_snapshot"

Treat ready as a usable base snapshot, generating or waiting as generation in progress, and failed as a signal to inspect attempts and logs. During a background refresh, the older snapshot can remain bootable while the API reports generating or waiting. The public environment resource has no marker that distinguishes an explicit regeneration from a background refresh. Check base_snapshot.error even when status is ready: it may record a failed rebuild while an older snapshot remains usable. A ready macOS snapshot still needs a compatible host at restore time. See Snapshots in Environments for host compatibility and regeneration behavior.

Inspect Failed Attempts

List snapshots to see both ready and failed generation attempts.

curl -s "$WALLFACER_API/accounts/$ACCOUNT_ID/environments/$ENVIRONMENT_ID/snapshots" \
  -H "Authorization: Bearer $WALLFACER_TOKEN" \
  | jq ".data[] | {id, status, platform, size_bytes, description}"

Failed attempts include a description, but the useful details are in per-step logs:

curl -s "$WALLFACER_API/accounts/$ACCOUNT_ID/environments/$ENVIRONMENT_ID/snapshots/$SNAPSHOT_ID/logs" \
  -H "Authorization: Bearer $WALLFACER_TOKEN" \
  | jq ".data[] | {source, name, status, exit_code}"

Use the single-log route for stdout and stderr of a specific step.

Roll Back A Base Snapshot

If a regeneration produces a bad result, list older snapshots, choose a known-good ready snapshot, and promote it.

curl -s -X POST "$WALLFACER_API/accounts/$ACCOUNT_ID/environments/$ENVIRONMENT_ID/snapshots/$SNAPSHOT_ID/promote" \
  -H "Authorization: Bearer $WALLFACER_TOKEN" \
  -H "Idempotency-Key: promote-known-good-001"

Promotion changes the environment pointer. It does not boot a VM or recapture the disk.

Delete Old Attempts

You can delete old snapshots to free storage. The current base snapshot cannot be deleted until another ready snapshot replaces it.

curl -s -X DELETE "$WALLFACER_API/accounts/$ACCOUNT_ID/environments/$ENVIRONMENT_ID/snapshots/$SNAPSHOT_ID" \
  -H "Authorization: Bearer $WALLFACER_TOKEN"

Failed attempts are usually safe to delete after you have read their logs.

Logs By Scope

Use the narrowest log route that matches what failed.

Logs capture manifest-step stdout, stderr, status, exit code, and timing. Events provide the higher-level timeline.

Common Failure Patterns

missing_secrets means the manifest references ${secrets.NAME} but that secret does not exist on the environment. Create or rotate the secret, then patch or regenerate.

missing_branch means a manifest source names a branch that no longer exists in its repository. An explicit snapshot regeneration returns 422 with repo, branch, and available branches; an automatic generation records the diagnostic in the environment base_snapshot.error and its logs. A previous base snapshot can remain ready; without one, base_snapshot.status becomes failed. Change the pinned branch in the manifest, then regenerate.

Setup command failures mean the snapshot never became ready. Read the failed snapshot logs and fix the manifest command.

Service health check failures mean setup may have succeeded but a long-running service never reached readiness. Check service logs and the health check definition.