VM Lifecycle

Every Wallfacer session runs inside an isolated virtual machine. Direct VM API calls create VMs explicitly; managed coding sessions create and tear down their own VMs as the session moves through its lifecycle.

Fresh Boot

When no usable snapshot exists for the environment, the VM starts from a base image and applies the environment manifest:

Base image
  -> Resolve environment manifest
    -> Clone sources
      -> Run setup commands
        -> Start services
          -> Pass service health checks
            -> Ready for API and session traffic

Setup commands run sequentially. Services can start concurrently, but depends_on controls dependency order. A setup or service health-check failure leaves the VM in failed status.

Snapshot Boot

When the environment has a ready base snapshot, the VM restores from the prepared disk instead of rerunning setup from scratch:

Restore snapshot
  -> Inject fresh credentials and boot-time env
    -> Reconcile source state
      -> Start services
        -> Pass service health checks
          -> Ready for API and session traffic

Setup commands are skipped because their results are baked into the snapshot. Services still start fresh on each boot.

Ready State

When you query a VM with the API, ready reports that the in-VM agent is accepting requests. It returns to false if the VM later fails, stops, or is destroyed; a non-null destroyed_at also means it is no longer ready. On macOS, ready: true can precede the host SSH check and port setup. For command execution, wait until SSH works; for public service URLs, wait for the expected port_mappings. ready_at keeps the time when the VM first became ready, even after it stops.

The status field tracks the VM lifecycle:

When a VM fails, inspect error for the reported cause. Some failures include a fallback message when no specific cause was reported, and error can also be null. Check the VM logs for more detail.

The phase field gives progress during boot. Values roughly follow manifest lifecycle work such as clone, setup, services, and ready. Treat unknown phase values as opaque so your client keeps working when new phases are added.

Port Mappings

Services that declare ports in the manifest get public URLs assigned by the platform. These appear in the VM's port_mappings array after the host finishes port setup. On macOS, ready: true can appear first, so wait for the expected mappings before using their URLs:

{
  "port_mappings": [
    {
      "name": "web",
      "port": 3000,
      "protocol": "http",
      "url": "https://example.wallfacer.dev"
    }
  ]
}

Use the name field from the manifest to choose the right URL. Do not rely on array order.

Idle Timeout

Managed sessions default to a 300-second idle timeout. You can set idle_timeout_seconds on task or session creation between 60 and 900 seconds.

When the timeout elapses, Wallfacer:

1. Marks the session idle.
2. Destroys the backing VM.

The idle timer is based on session activity. Sending a message resets it.

Resuming

When you send a message to an idle session:

1. A new VM boots from the session's environment.
2. Fresh credentials and configuration are injected.
3. The session transcript is made available to the agent.
4. Services restart and health checks pass.
5. The queued message is delivered.

Posting a message can also reactivate a closed session when the platform can safely do so. Terminal failures such as setup failure, snapshot failure, or capacity exhaustion may require fixing the underlying problem first.

Destruction

VMs are destroyed by:

• Idle timeout: managed session inactivity.
• Task pause: the task pauses and no running session still uses its sandbox VM.
• Explicit close: user or API closes the session.
• Direct VM delete: DELETE /v1/accounts/{account}/vms/{vm}.
• Infrastructure reclamation: the platform needs to free resources.

While a host is reachable, Wallfacer flushes mounted storage before destroying a VM. Destruction removes the VM disk, memory, and processes. Session records and messages remain available through the task/session APIs.

If a Linux pool host stops responding, Wallfacer terminates it after the offline grace period and releases its remaining VM records. Deleting a VM whose host was already removed also completes without waiting for that host. An unreachable host cannot flush pending writes or recover files left only on its local disk. Check the mounted bucket for the files you need; an upload that had not reached the bucket cannot be recovered from the terminated host.

Snapshot Lifecycle

Snapshots are environment generation attempts. They are what make later VM and session boots fast.

1. Generation: Wallfacer boots a temporary VM, applies the manifest, and captures a ready disk.
2. Promotion: A ready snapshot becomes the environment's base_snapshot.
3. Restore: New VMs and sessions boot from the current base snapshot unless a specific snapshot_id is supplied.
4. Refresh: Wallfacer periodically rebuilds a snapshot that has aged and swaps in the fresh one once it's ready, so the current snapshot keeps serving boots in the meantime.
5. Self-heal: If the current base snapshot can't be restored, the boot falls back to a fresh build and a rebuild runs in the background, so the session still starts.
6. Failure: Failed attempts remain listable so you can inspect logs.
7. Rollback: Promote an older ready snapshot to make it the base again.

Use the snapshot routes to list attempts, inspect logs, delete old snapshots, and promote a known-good snapshot.