Run a task on a machine

Cmdop runs a task on a joined machine three ways: a browser conversation you watch and approve, the cmdop chat and cmdop fleet CLI commands, or the typed Python and Node SDK. Choose by who reads the result — a person reviewing changes uses the browser, a script uses the SDK.

Choose a path

There are three paths, and the right one depends on who is reading the result.

Browser path

1. Open the machine workspace with cmdop open.
2. Select the machine that owns the files and tools.
3. Choose a Project Root when the task belongs to a repository.
4. Start or resume a conversation.
5. State a bounded outcome, constraints, and how the result should be checked.
6. Review changes and follow-up questions before accepting the result.

Example:

Inspect this repository’s current status and test configuration. Recommend one small next step, but do not modify files.

CLI path

cmdop chat talks to this machine’s agent; cmdop fleet <machine> talks to another machine’s agent, with an interactive picker when you omit the name. Both have a one-shot form for scripts. See CLI machine chat for the full command surface.

SDK path

Install the published Python package. Client() uses the active local Cmdop setup; remote configuration is covered in SDK configuration. Then select a connected machine explicitly:

from cmdop import Client
 
async with Client() as client:
    snapshot = await client.machines.list()
    connected = [machine for machine in snapshot.machines if machine.connected]
    if not connected:
        raise RuntimeError("No online Cmdop machine is available")
 
    machine = connected[0]
    result = await client.machines.ask(
        machine.machine_id,
        "Report the machine uptime. Do not change system state.",
        pin="1234",  # only if the machine is PIN-protected
    ).collect()
    print(result)

collect() returns final text or raises AgentStreamError for an unsuccessful terminal outcome. Supply a connection PIN before streaming begins when the target requires one. The complete Python and Node contract is in SDK streaming.

Common questions

How should I ask an AI agent to run a task on another machine?

Start by naming the target machine and the bounded outcome. For interactive human review, use the browser or cmdop fleet <machine>; for typed programmatic results, use the SDK. In either case, keep the target explicit and pass a PIN before the stream starts when the machine requires one.

When should I use the SDK instead of the browser?

Use the SDK when another program needs the result and must handle streaming outcomes in code. Use the browser when a person should watch progress, answer questions, approve edits, and decide whether the result is good enough.

Can a task run on a server behind NAT?

Yes, if the server has joined Cmdop and its agent is online. The task is sent through the fleet relationship rather than to a public server address. For the setup path, see Let an AI agent reach a machine behind NAT.