Machines

Methods

Authoritative snapshot

list() returns a snapshot, not a paginated collection:

snapshot = await client.machines.list()
 
print(snapshot.epoch, snapshot.sequence)
for machine in snapshot.machines:
    print(machine.machine_id, machine.display_name, machine.presence)

Every row identifies the machine (machine_id, display_name) and reports whether it is reachable right now — presence is online, stale, or offline.

Rows also carry host details and resource metrics when the machine has reported them: what it is running on, and how loaded it is. These are best-effort, so read them defensively and treat a missing value as unknown rather than as a zero.

Node scalar types

Public resource IDs such as machineId, message id, and attachment id are strings. Protobuf int64 fields are bigint in Node, including snapshot sequence, unread counts, message seq and createdAt, byte counters, and token counts on a completed ask.

Convert bigint values when serializing to JSON:

const json = JSON.stringify(snapshot, (_key, value) =>
  typeof value === "bigint" ? value.toString() : value,
);

Ask one machine

text = await client.machines.ask(
    machine_id,
    "Summarize the current system load.",
    pin="1234",
    session="2",
).collect()

Supply the connection PIN up front when the target requires it. Other typed options are attachment_ids, engine, working_dir, project_root_id, and model. See Streaming for frame handling.

Durable messages

history = await client.machines.messages(machine_id, session="2", limit=100)
 
for message in history.messages:
    print(message.seq, message.role, message.content)

limit must be between 1 and 500. Each message includes its stable id, sequence, author, role, content, and creation timestamp; tool/event metadata and attachments are included when present.