Virtual Machines

VMs are the lower-level infrastructure API. Use them when you need direct control over a running machine rather than a managed coding session.

Every VM boots from an environment. The environment manifest determines platform, sources, setup, services, ports, and simulator configuration. The public VM create endpoint accepts environment_id, optional snapshot_id, and optional boot-time environment variables; it does not accept a raw manifest.

Boot A VM

curl -s -X POST "$WALLFACER_API/accounts/$ACCOUNT_ID/vms" \
  -H "Authorization: Bearer $WALLFACER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: vm-smoke-test-001" \
  -d '{
    "environment_id": "'$ENVIRONMENT_ID'",
    "env": {
      "NODE_ENV": "test"
    }
  }' | jq ".data"

The response is immediate. Boot continues asynchronously.

If the environment has a ready base snapshot, boot is fast. Otherwise the VM has to run setup fresh.

Wait For Readiness

Poll the VM until ready is true.

while true; do
  vm=$(curl -s "$WALLFACER_API/accounts/$ACCOUNT_ID/vms/$VM_ID" \
    -H "Authorization: Bearer $WALLFACER_TOKEN")

  ready=$(echo "$vm" | jq -r ".data.ready")
  status=$(echo "$vm" | jq -r ".data.status")
  phase=$(echo "$vm" | jq -r ".data.phase // \"pending\"")

  echo "$status $phase ready=$ready"

  [ "$ready" = "true" ] && break
  [ "$status" = "failed" ] && exit 1
  sleep 3
done

Use phase for progress display. Values roughly follow clone, setup, services, and ready, but clients should treat unknown values as opaque.

Use Exposed Ports

Services in the manifest can expose ports. Once the VM is ready, public URLs appear in port_mappings.

curl -s "$WALLFACER_API/accounts/$ACCOUNT_ID/vms/$VM_ID" \
  -H "Authorization: Bearer $WALLFACER_TOKEN" \
  | jq ".data.port_mappings"

Each mapping includes a service name, port, protocol, and URL. Use names from the manifest instead of assuming port order.

Run Commands

Command execution is synchronous. The API returns exit_code, stdout, and stderr.

curl -s -X POST "$WALLFACER_API/accounts/$ACCOUNT_ID/vms/$VM_ID/commands" \
  -H "Authorization: Bearer $WALLFACER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "npm test",
    "working_directory": "/workspace/my-api",
    "timeout": 120
  }' | jq ".data"

Use direct command execution for smoke tests, diagnostics, one-off builds, or integration hooks. For AI coding, prefer tasks and sessions.

Pin A Snapshot

By default, a VM uses the environment's current base snapshot. Pass snapshot_id only when you need to pin a specific ready snapshot, such as for a rollback or reproducibility test.

{
  "environment_id": "019d8e44-e110-71f6-864b-8e91470dcc4a",
  "snapshot_id": "snap-019d8e44-a1b2"
}

The snapshot must belong to the referenced environment.

Destroy VMs

Destroy direct VMs when you are done.

curl -s -X DELETE "$WALLFACER_API/accounts/$ACCOUNT_ID/vms/$VM_ID" \
  -H "Authorization: Bearer $WALLFACER_TOKEN"

Managed sessions handle their own VM teardown when they go idle or close. Direct VMs are your responsibility.