Connecting a machine.

The host

The host is the program that gives the workbench this computer's files and the machines attached to it. There is exactly one host per computer. The desktop app is a host; so is the background service, started with commandagi daemon start. When the desktop app starts, it takes over from a running service.

The host listens on 127.0.0.1 only (port 4173 by default, or any free port), and keeps its state in ~/.commandagi:

The commandagi command

commandagi daemon start [--port N] [--project DIR] [--name X] [--no-platform]
commandagi daemon status | stop | logs
commandagi daemon run   [same flags, in the foreground]
commandagi mcp [--credential-file F]
commandagi grant add | list | revoke …
commandagi threed install | status
commandagi code eval <path> [--input name=value]…

• daemon start runs the host in the background and logs to ~/.commandagi/daemon.log. --no-platform hosts locally without linking to an account.
• daemon stop refuses while the desktop app is the host — quit it from the app instead.
• mcp is the stdio relay for agents (see SDK and MCP). grant makes and revokes standing grants (see Agents and standing grants).
• threed installs the local 3D design service; code eval evaluates a code part headlessly and prints its operation graph as JSON.

Link the host to your account

A host linked to an account can be reached from that account's workbench anywhere, and acts as that account. Linking is signing in:

• in the desktop app, sign in when it asks;
• at the workbench page served by the host, sign in from the left dock — the host checks the key and keeps it;
• from a shell, set COMMANDAGI_API_KEY to an API key before starting the daemon.

The account key is kept in host.json, an owner-only plain file, so a copied ~/.commandagi stays signed in. Signing out removes it.

Pair hosts with each other

Hosts on different computers can pair, both ways, in one act: one host offers, the other accepts. Pairing is always a person's decision. Once paired, agents can list the other hosts and call them — within whatever grants exist there.

Page drivers: USB and Bluetooth from the browser

Some drivers run in the workbench page itself, using WebSerial and Web Bluetooth. A browser opens a port only when you pick it, so an agent always uses a connection a person made and never opens one on its own. Network machines (a printer's HTTP API, a FluidNC controller on TCP) are driven by the host.

Drivers that listen for machines dialling in over the LAN need the setting "devices.lanListener": true.

Driver catalog

Every driver says what it has been verified against: none, loopback (against a faithful software fake of the protocol), bench or hardware. A driver never claims more than was done. No machine has been commissioned on hardware yet.

Simulation worlds use two simulators instead: gcode-sim for G-code channels and servo-sim for servo buses.

Next

Give an agent authority over a machine: Agents and standing grants.