VMs

List, inspect, and delete VMs, and manage their sessions.

The VM object

vm_id

String

The VM's id.

name

String | null

The VM's name, if one was given at fork time.

state

"running" | "idle"

Lifecycle state. A run against an idle VM auto-resumes it.

provider, region

String

Where this VM runs, from the worker's own [worker] config.

platform

String

The backend's platform identifier for this VM.

resources

Object

Provisioned resources: vcpu, memory_mib, disk_mib.

The Session object

A session is a persistent shell whose working directory and environment survive across runs. A VM gets a default session the first time it runs a command without an explicit session_id; open more with create session.

session_id

String

The session's id.

session_idx

Int

Its index on the VM; the first session created is 0.

state

"idle" | "running"

Lifecycle state.

cwd

String

Current working directory.

env

Object | null

Environment-variable overrides for the session, if any were set.

GET/v1/vms

List every VM known to this worker.

Response

vms

Array

An array of VM objects.

Example

bash

curl localhost:7240/v1/vms

GET/v1/vms/{id}

Fetch a single VM.

Response

Returns a VM object.

Example

bash

curl localhost:7240/v1/vms/$VM

DELETE/v1/vms/{id}

Delete a VM and release its resources.

Response

deleted

Bool

true once the VM is gone.

Example

bash

curl -X DELETE localhost:7240/v1/vms/$VM

GET/v1/vms/{id}/sessions

List a VM's sessions.

Response

sessions

Array

An array of Session objects.

next_cursor

null

Always null today; session listing is not paginated.

Example

bash

curl localhost:7240/v1/vms/$VM/sessions

POST/v1/vms/{id}/sessions

Open a new session on a VM.

Request

cwd

String

Starting working directory. Defaults to /.

env

Object

Environment-variable overrides for the session.

Response

Returns a Session object.

Example

bash

curl -X POST localhost:7240/v1/vms/$VM/sessions \
  -H "Content-Type: application/json" \
  -d '{"cwd":"/tmp"}'

DELETE/v1/vms/{id}/sessions/{sid}

Close a session.

Response

deleted

Bool

true once the session is closed.

Example

bash

curl -X DELETE localhost:7240/v1/vms/$VM/sessions/$SID