Machines
A machine is a computer running monoclaw and connected to your account. This page covers everything after the first one. For the first, follow the Quick start.
Add another machine
Section titled “Add another machine”You need Node.js 22 or newer on the computer, as before.
- In the app, open the menu on your name and choose Machines.
- Choose Add a machine. If you own more than one space, pick the one it joins under Add to.
- Copy the command and run it in a terminal on that computer. It is the same one command as in the Quick start, on every system.
You should see the new machine in the list as Online. It has no modules yet: open it and add what it should do, starting with Claude if it will run agents.
Run it in the background
Section titled “Run it in the background”The install command starts the machine in the background. You can also do that yourself at any time:
monoclaw service installIt starts the machine now and at every login, and restarts it if it stops. It never uses sudo. Run it again to restart the machine.
| System | How it runs |
|---|---|
| macOS | A launchd agent, ai.monoclaw.host |
| Linux | A systemd user unit, monoclaw.service |
| Windows | A Task Scheduler task, “MonoClaw host”, that starts when you log on |
On every system the machine writes its log to ~/.monoclaw/host/logs/host.log. On Linux you can also follow it with journalctl --user -u monoclaw -f.
To stop it and remove the background service:
monoclaw service uninstallTo run it in a terminal instead, where you can watch it, use monoclaw start. It stops when you close the terminal. Only one copy can run per machine.
Allowed folders
Section titled “Allowed folders”Agents on a machine can only be given folders inside its allowed folders. They are set on the machine itself, so nothing in the app or the service can widen them.
List them:
monoclaw roots listAdd one. The folder must exist already:
monoclaw roots add ~/projectsRemove one:
monoclaw roots remove ~/projectsRestart the machine for a change to reach the app: run monoclaw service install again, or stop and start monoclaw start. You cannot add a folder that contains MonoClaw’s own settings folder, ~/.monoclaw/host, such as your whole home folder.
Allowed folders are not a sandbox. See Security.
The machine’s page
Section titled “The machine’s page”Choose a machine in Machines to open it.
- Status: the space it belongs to, online or offline, system, version and when it was last seen.
- Allowed folders: the list, and which agents use each.
- Modules: what the machine can do, each with its state (Installing, Ready, Needs setup or Error). Add module shows what this machine can install. Setup steps shows the commands to set a module up by hand. Under a module are its connections: Add a key, Enter key or Replace key, Check and Remove.
- Agents on this machine: every agent that runs here, with its project.
- Rename, Move to… (to another space you own) and Remove this machine.
A key you type here is encrypted in your browser for that machine. See Security. What each module needs is on its page under Modules.
Updates
Section titled “Updates”A machine updates itself. It checks when it starts, every six hours, and shortly after it reconnects, and it waits for agents to finish what they are doing before it restarts. Machines shows Update beside a machine that is behind.
To update now:
monoclaw updateThen restart the machine. See Troubleshooting if a machine stays behind.
One computer in several spaces
Section titled “One computer in several spaces”A machine belongs to one space. To use the same computer in a second space, such as an organisation, add it again from that space: choose Add a machine there and run its command on the computer. MonoClaw sees that the computer already works for another space, asks you, and connects it a second time under a profile named after the new space. Its folders are kept.
Each profile is its own machine in the app, with its own name, folders, modules, keys and background service. Downloaded models and the computer’s Claude login are shared. Every command for the second one carries the profile, for example:
monoclaw --profile acme service installThe first enrolment is untouched. To move a machine to another space instead of sharing the computer, use Move to… on its page.
Servers without a screen
Section titled “Servers without a screen”A server works like any other machine. Three things differ:
- Claude sign-in.
monoclaw claude auth loginneeds no browser on the server: it prints a link: open the link on any device, sign in, and paste the code it gives you back into the terminal. - Logging out. Run
loginctl enable-linger $USERso the machine keeps running. - Keys. Without a desktop keyring, API keys are kept in a file only your user can read.
Remove a machine
Section titled “Remove a machine”- Open the machine’s page and choose Remove this machine. The app lists the agents that will stop. Their projects stay.
- On the computer, stop the background service:
monoclaw service uninstallYou should see the machine gone from Machines. Its connection is revoked; you can add it again at any time.
See what a machine thinks
Section titled “See what a machine thinks”monoclaw statusshows what it is connected to, its folders and whether each module is ready. monoclaw doctor checks more and says how to fix what it finds. Every command is listed under Commands.