Machines API

From code, one snapshot call returns every machine in the fleet with its identity and whether it is reachable right now — online, stale, or offline. A second call asks one machine to do something and streams the agent’s work as it goes. Adding a machine is not a code operation; it happens on the machine.

Everything about a machine — is it there, what is it running on, is it busy — comes from one snapshot call.

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

list() returns the current state of the whole fleet, not a page of it. Each row identifies the machine and reports whether it is reachable right now: online, stale, or offline.

Rows also carry host details and load figures when the machine has reported them. Read those defensively — a missing value means the machine did not report it, not that the value is zero.

See Machines for the full method surface and the Node type notes.

Ask a machine to do something

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

ask() streams as the agent works. collect() waits for the final text when you only want the answer; iterate the stream when you want to show progress — see Streaming.

You can pin the engine, the working directory, the project scope, and the model per request. A connection PIN goes in with the request when the target machine requires one.

From the command line

cmdop machines          # list machines
cmdop status            # this machine's connection verdict
cmdop remotes list      # the relays this machine knows about

cmdop connect <machine> attaches an interactive terminal to a machine, which needs the target behind a public or own-domain relay — see Connection issues.

Adding and removing machines is not a code operation

A machine joins by running cmdop join on the machine itself, with the fleet join key. There is no call that adds a machine remotely, by design: only someone with access to the machine can bring it into a fleet. See Self-hosted relay.

Related

• Machines (SDK)
• Machine health
• Programmatic access

Common questions

How do I list machines from code?

Call client.machines.list(). It returns the current fleet snapshot with each machine’s identity and presence state, including whether it is online, stale, or offline.

Can code add a machine to a fleet?

No. A machine joins by running cmdop join on that machine with the fleet join key. There is no remote API call that adds a computer to a fleet.

How do I ask one machine to do work from code?

Call client.machines.ask(machine_id, request) and stream the result or call collect() for final text. Pass a connection PIN in the request when the target machine requires one.