watchCvmState

Watch CVM state changes via Server-Sent Events until a target status is reached

​

watchCvmState

GET /cvms/{cvmId}/state (Server-Sent Events)

Watches CVM state changes in real-time via Server-Sent Events (SSE). Resolves when a completion event confirms the target status. A timeout applies to one attempt; the client retries by default without a limit. It also retries when the stream ends before completion. Cancellation aborts the watch.

Parameters:

Field	Type	Required	Description
id	string	Yes	CVM identifier
target	string	Yes	Target status to wait for (e.g., "running", "stopped")
interval	number	No	Polling interval in seconds (5-30, default: 5)
timeout	number	No	Per-attempt timeout in seconds (10-600, default: 300)
maxRetries	number	No	Maximum retries after the first request (default: Infinity); 0 still makes one request
retryDelay	number	No	Delay between retries in ms (default: 5000)

Options:

Field	Type	Description
signal	AbortSignal	Cancellation signal
onEvent	(event) => void	Callback for each SSE event

Returns: CvmState — the latest state received when a completion event confirms the target. The state’s raw status can differ from the derived status used for that comparison.

Field	Type	Description
id	string	CVM ID
instance_id	string	Instance ID
name	string	CVM name
status	string	Raw CVM status
uptime	string?	Uptime duration
boot_progress	string?	Boot progress
boot_error	string?	Boot error if failed

Errors:

Error	Description
WatchAbortedError	Thrown when the operation is cancelled via AbortSignal
MaxRetriesExceededError	Thrown when retries are exhausted after a timeout or an incomplete stream

A server error event may be followed by more events. When MaxRetriesExceededError is raised, lastServerError may contain the latest server error event data, which is also included in the error message. lastAttemptError may contain the last transport error. If retries end on a transport error without a server diagnostic, that error is thrown directly.

Example — Wait for CVM to start:

import { createClient, watchCvmState } from "@phala/cloud";

const client = createClient();
const state = await watchCvmState(client, {
  id: "my-app",
  target: "running",
  timeout: 120,
}, {
  onEvent: (event) => {
    if (event.type === "state") {
      console.log(`Status: ${event.data.status}`);
    }
  },
});

console.log(`Latest raw CVM status: ${state.status}`);

Example — With abort support:

import { createClient, watchCvmState, WatchAbortedError } from "@phala/cloud";

const client = createClient();
const controller = new AbortController();

// Cancel after 60 seconds
setTimeout(() => controller.abort(), 60_000);

try {
  const state = await watchCvmState(client, {
    id: "my-app",
    target: "running",
  }, { signal: controller.signal });
} catch (error) {
  if (error instanceof WatchAbortedError) {
    console.log("Watch was cancelled");
  }
}

Unlike other SDK functions, watchCvmState does not have a safe variant. Use try/catch for error handling.