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, the ready field is the client-facing readiness signal. It flips to true once the VM has completed boot and the in-VM agent is accepting requests.

The status field tracks the VM lifecycle:

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 once the VM is ready:

{
  "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.
• 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.

Destruction removes the VM disk, memory, and processes. Session records and messages remain available through the task/session APIs.

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.