Skip to content

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.

You need Node.js 22 or newer on the computer, as before.

  1. In the app, open the menu on your name and choose Machines.
  2. Choose Add a machine. If you own more than one space, pick the one it joins under Add to.
  3. 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.

The install command starts the machine in the background. You can also do that yourself at any time:

Terminal window
monoclaw service install

It 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:

Terminal window
monoclaw service uninstall

To 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.

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:

Terminal window
monoclaw roots list

Add one. The folder must exist already:

Terminal window
monoclaw roots add ~/projects

Remove one:

Terminal window
monoclaw roots remove ~/projects

Restart 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.

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.

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:

Terminal window
monoclaw update

Then restart the machine. See Troubleshooting if a machine stays behind.

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:

Terminal window
monoclaw --profile acme service install

The first enrolment is untouched. To move a machine to another space instead of sharing the computer, use Move to… on its page.

A server works like any other machine. Three things differ:

  • Claude sign-in. monoclaw claude auth login needs 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 $USER so the machine keeps running.
  • Keys. Without a desktop keyring, API keys are kept in a file only your user can read.
  1. Open the machine’s page and choose Remove this machine. The app lists the agents that will stop. Their projects stay.
  2. On the computer, stop the background service:
Terminal window
monoclaw service uninstall

You should see the machine gone from Machines. Its connection is revoked; you can add it again at any time.

Terminal window
monoclaw status

shows 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.