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. When generation fails, the failed snapshot attempt is preserved so you can inspect logs.

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 a snapshot that has aged or rebuilds one that couldn't be restored. These run in the background, so base_snapshot.status can move to generating without an explicit request from you.

Explicit regeneration returns 202 Accepted; the work continues asynchronously.

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 usable, generating as in progress, and failed as a signal to inspect snapshot attempts and logs.

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.

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.