Sessions API
A Cmdop session is a durable work thread that lives on the machine, so code should resume a session rather than start a new one on every reconnect. Its history is readable afterwards, including turns that ran with nobody attached, and other operators may be working in the same session at the same time.
A Cmdop session is the durable work thread on a machine. It survives your disconnect, so code that reconnects should resume a session rather than start a fresh one — see Durable conversations.
Resume the same session
Every call that drives a machine takes the session to work in. Pass the same value again and you continue that thread, with its history and its context intact:
stream = client.machines.ask(
machine_id,
"Continue where we left off.",
session="2",
)Omit it and you get the machine’s default session. Use an explicit session when a program owns a long-running line of work and should not collide with what a person is doing in the browser.
Read what happened while you were away
The session’s history is durable and readable, including turns that ran with nobody attached:
history = await client.machines.messages(machine_id, session="2", limit=100)
for message in history.messages:
print(message.seq, message.role, message.content)That is the reason for the model: a program can drop off, come back later, and find out what happened, rather than having to hold the connection open to observe.
Sessions are shared, not private
The session lives on the machine, not in your client. Another operator — a person in the browser, an assistant over MCP, another program — can be attached to the same session at the same time, and everyone sees the same live state. Changing the session’s project scope or engine changes it for all of them.
Write code accordingly: your process is one operator among several, not the owner of the session.
Related
Common questions
Should code resume a Cmdop session?
Yes when the work is part of a durable thread. Pass the same session id again so your program continues the same machine-owned context instead of starting a fresh conversation every time it reconnects.
Can I read what happened after my process disconnected?
Yes. Read the session’s durable message history. The session lives on the machine, so work that ran while your process was gone can still be inspected after reconnect.
Are API sessions private to one process?
No. A session is shared live state on a machine. A browser operator, MCP assistant, and program can all be attached to the same session, so code should not assume it is the only operator.
Cmdop