Skip to Content
Referenceoo CLI

oo machines

Computers agents run commands on, as OpenClaw nodes.

Connect a computer, such as your laptop, to agents of this Sunport as an OpenClaw node. Each agent may then run commands on it, within the level and allowlist set for that agent: run takes only the programs on the allowlist, full takes any, and read only finds programs. It needs the Sunport's Machines service, and works for the VM agents that service lists.

oo machines add prints the line to run on the computer, with a one-time code that lasts 15 minutes: a shell line for Linux and macOS, a PowerShell line for Windows (--os windows). The script there prints three match words: compare them with oo machines get before oo machines approve; it also says whether each node is connected now. Rules change once the node is connected. Clem and managed agents with the grant may read machines; only people add, approve, change, revoke and remove them.

A service VM or an agent's VM of this Sunport can be a machine too, which people work on together: oo machines use-vm makes one, for whoever manages the VM, who becomes its first admin. Its admins add people and teams with oo machines members add, as members or admins. Everyone on a machine works as one Linux account there, and so can read and change what is on it: on a service VM the one chosen with --account, on an agent's VM the agent's own. Removing it leaves the VM, and it ends with the VM.

Its people work on it as themselves, as its account: oo machines ssh opens a terminal there, and oo machines cp and ls copy and list its files, from the account's home; a Sunport administrator's terminal is root's, which it asks first. Removing someone ends their terminal within a minute.

A VM machine starts with the Sunport's machine setup (oo machines setup), which the Sunport installs one step at a time; oo machines get shows the steps. What a machine has is its own: people change it on the machine, in its terminal or by asking an agent that works there, and oo machines env reads it.

oo machines pair lets a managed OpenClaw agent work on a VM machine, for a person who manages the agent and is an admin of the machine: the Sunport installs the agent's node there, which runs commands as the machine's account within the level and allowlist, as on a computer. oo agents machine then chooses where every chat with the agent runs its commands. oo machines revoke takes the node off the VM again.

oo machines list

List machines, with each agent's level and state

oo machines list

It also takes the connection options.

oo machines get

Show one machine, with its match words and whether its nodes are connected

oo machines get MACHINE_ID
ArgumentRequiredDefaultChoicesDescription
MACHINE_IDyesID from oo machines list

It also takes the connection options.

oo machines add

Add a machine for one or more agents, up to four, and print the line to run on it. Every agent given gets the same level and allowlist; change one later with oo machines rules.

oo machines add [options] name
ArgumentRequiredDefaultChoicesDescription
nameyesthe machine's name: letters, digits, spaces, dots, dashes and underscores
--agent AGENT_IDyesan agent that may use it; repeat for more
--level LEVELnoread, run, fullrun (default): only the --allow programs; full: any program, the default on Windows, which takes full and read only; read: none, it only finds them
--allow PATHnoa program's full path the agents may run at level run; repeat for more
--os OSnolinuxlinux, macos, windowslinux (default), macos or windows
--lock-rulesnothe computer keeps the rules it starts with: nobody changes them from the Sunport
--expires TIMEnowhen every agent's access ends, in UTC (ISO 8601), within a year

It also takes the connection options.

oo machines approve

Approve a machine whose match words you compared

oo machines approve MACHINE_ID
ArgumentRequiredDefaultChoicesDescription
MACHINE_IDyesID from oo machines list

It also takes the connection options.

oo machines reject

Reject a machine; its code no longer works

oo machines reject [options] MACHINE_ID
ArgumentRequiredDefaultChoicesDescription
MACHINE_IDyesID from oo machines list
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat

It also takes the connection options.

oo machines rules

Change what one agent may run on a connected machine

oo machines rules [options] MACHINE_ID AGENT_ID
ArgumentRequiredDefaultChoicesDescription
MACHINE_IDyesID from oo machines list
AGENT_IDyesthe agent, as oo machines get lists it
--level LEVELnorun, fullrun or full; moving to or from read needs a new machine
--allow PATHnoa program's full path; the ones given replace the allowlist; repeat for more

It also takes the connection options.

oo machines revoke

End one agent's access to a machine at once

oo machines revoke [options] MACHINE_ID AGENT_ID
ArgumentRequiredDefaultChoicesDescription
MACHINE_IDyesID from oo machines list
AGENT_IDyesthe agent, as oo machines get lists it
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat

It also takes the connection options.

oo machines pair

Let a managed OpenClaw agent work on a VM machine and print its pairing: the Sunport installs the agent's OpenClaw node on the VM, as the machine's account, which takes a few minutes. On another agent's VM it works as a normal user, and that agent can still read and change what it does there. It needs you to manage the agent and to be an admin of the machine. Hermes, container and connected agents keep where they run.

oo machines pair [options] MACHINE_ID AGENT_ID
ArgumentRequiredDefaultChoicesDescription
MACHINE_IDyesID of a VM machine from oo machines list
AGENT_IDyesthe agent, by its ID from oo agents list
--level LEVELnoread, run, fullrun (the default): only the --allow programs; full: any program, the default where the node runs as root, which takes no run (the machine's levels); read: none, it only finds them
--allow PATHnoa program's full path the agent may run at level run; repeat for more

It also takes the connection options.

oo machines remove

Remove a machine, ending every agent's access to it; a VM machine leaves its VM

oo machines remove [options] MACHINE_ID
ArgumentRequiredDefaultChoicesDescription
MACHINE_IDyesID from oo machines list
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat

It also takes the connection options.

oo machines use-vm

Make a VM of this Sunport a machine people work on together. It takes hosts.manage on the VM, and only one the Sunport signs in to: a service VM made with Clem managing it, or an agent's VM. You become its first admin. Everyone on it works as one Linux account: on a service VM the one --account names, on an agent's VM the agent's own.

oo machines use-vm [options]
ArgumentRequiredDefaultChoicesDescription
--vm NAMEnoa service VM, by the name it was made with (oo vm inventory)
--agent AGENT_IDnothe VM an agent runs on, by the agent's ID
--name NAMEnothe machine's name: letters, digits, spaces, dots, dashes and underscores
--account ACCOUNTnoroot, machinewith --vm, which it needs: root, or the user machine without sudo

It also takes the connection options.

oo machines members

List, add and remove the people and teams who work on a VM machine. Its admins change them: an admin also adds and removes people, a member only works on it.

oo machines members [COMMAND]

It also takes the connection options.

oo machines members list

Who works on it, and whom an admin may add

oo machines members list MACHINE_ID
ArgumentRequiredDefaultChoicesDescription
MACHINE_IDyesID from oo machines list

It also takes the connection options.

oo machines members add

Add a person or a team, or change their role

oo machines members add [options] MACHINE_ID
ArgumentRequiredDefaultChoicesDescription
MACHINE_IDyesID from oo machines list
--person PERSON_IDnoa person, by their ID from oo people list
--team TEAMnoa team, by its name or ID
--role ROLEnomembermember, adminmember (default) works on it; admin also adds and removes who works on it

It also takes the connection options.

oo machines members remove

Stop a person or a team working on it

oo machines members remove [options] MACHINE_ID
ArgumentRequiredDefaultChoicesDescription
MACHINE_IDyesID from oo machines list
--person PERSON_IDnoa person, by their ID from oo people list
--team TEAMnoa team, by its ID from oo machines members list

It also takes the connection options.

oo machines ssh

Open a terminal on a VM machine in this terminal, as the machine's Terminal tab does: as the machine's account, from its home, or as root for a Sunport administrator, which it asks first, or takes --yes. The VM's log and the Sunport's audit name you. It ends when the shell exits or you no longer work on the machine; oo then exits 0 if it ended normally, 1 otherwise.

oo machines ssh [options] NAME
ArgumentRequiredDefaultChoicesDescription
NAMEyesthe machine, by its name or ID from oo machines list
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat

It also takes the connection options.

oo machines cp

Copy a file, or a folder with -r, between this computer and a VM machine, as the machine's Files tab does: as the machine's account, a Sunport administrator's too. NAME:PATH is the machine's side; PATH is absolute or from the account's home. An upload replaces a file there only once all of it arrived, and a folder goes to a new folder. A broken download goes on from where it stopped with --continue.

oo machines cp [options] source destination
ArgumentRequiredDefaultChoicesDescription
sourceyesa path on this computer, or NAME:PATH on the machine
destinationyesNAME:PATH on the machine, or a path on this computer
-r, --recursivenocopy a folder, as a tar packed and unpacked on the fly
--continuenogo on with a download that stopped, from its NAME.oo-partial file
--overwritenoreplace a file already at the local destination

It also takes the connection options.

oo machines ls

List a folder on a VM machine as oo machines cp copies: its entries, each with its type, and a file's size. NAME:PATH, PATH absolute or from the account's home; NAME alone lists the home.

oo machines ls NAME[:PATH]
ArgumentRequiredDefaultChoicesDescription
NAME[:PATH]yesthe machine, and a folder on it

It also takes the connection options.

oo machines setup

The Sunport's machine setup: Debian packages, runtimes (Node with pnpm, Python with uv) and a setup script. The Sunport installs it on a VM when it becomes a machine, one step at a time, and again when one of the machine's admins applies it. Each step skips what the machine has. Administrators change it (settings.write); a change leaves existing machines alone.

oo machines setup [COMMAND]

It also takes the connection options.

oo machines setup get

Show the setup, and who changed it last

oo machines setup get

It also takes the connection options.

oo machines setup set

Replace the setup with the one given

oo machines setup set [options]
ArgumentRequiredDefaultChoicesDescription
--package NAMEnoa Debian package; repeat for more
--node MAJORnoNode's major version, such as 22; it comes with pnpm
--python VERSIONnoPython's version, such as 3.13; it comes with uv
--script-file PATHnothe setup script, run as root with bash -e after the rest; - reads it from stdin. It runs again each time the setup is applied, so it must be safe to run again

It also takes the connection options.

oo machines setup apply

Install the setup as it is now on a VM machine, from its first step; its admins only

oo machines setup apply MACHINE_ID
ArgumentRequiredDefaultChoicesDescription
MACHINE_IDyesID from oo machines list

It also takes the connection options.

oo machines env

What a VM machine has, read from it now: its system, runtimes and tools, and when the setup went on it

oo machines env MACHINE_ID
ArgumentRequiredDefaultChoicesDescription
MACHINE_IDyesID from oo machines list

It also takes the connection options.

On this page