Connect to a Host
Control commands call a running Host over HTTP:
POST {DIMO_URL}/api/v1/call/{command}
Authorization: Bearer {DIMO_TOKEN}
Content-Type: application/json
x-dimo-protocol-version: 1.0The body is { "operation_id": "<uuid>", "args": { ... } }. On success, stdout prints data. On HTTP error the process exits non-zero and prints code: message.
Start the Host first (npx dimo or npx dimo serve), export the token in the same shell, then run control commands such as npx dimo agent list.
Environment variables
| Variable | Role | Default |
|---|---|---|
DIMO_URL |
Host root URL; trailing slashes are stripped | http://127.0.0.1:17891 |
DIMO_TOKEN |
Host token, required | none; missing yields DIMO_TOKEN is required |
export DIMO_URL=http://127.0.0.1:17891
export DIMO_TOKEN='<paste-token>'
npx dimo agent listToken sources:
- The Token block from
npx dimo serve. - Access Token under desktop Settings → Remote connection, for the same Host.
- The value supplied as
DIMO_SERVER_TOKENat start.
Keep the token in the environment, the OS keychain, or the Host data directory. Repositories, chat logs, and shell history that will be committed should hold placeholders only. After rotation the previous token fails immediately; point every control command at the new value. Rotation is npx dimo serve --rotate-token.
After a port change, update DIMO_URL as well. If the Host ran npx dimo serve --port 18080, then export DIMO_URL=http://127.0.0.1:18080.
Local browser
With npx dimo serve --local or a loopback origin, open http://127.0.0.1:17891 on this machine. Web UI files come from DIMO_STATIC_ROOT (npx points at packaged web/). Agents, Git, and the terminal still execute on the Host machine.
With plain npx dimo (no serve), the token is omitted from the terminal by default. The local browser can still open the loopback origin; control commands need the token from the data directory or DIMO_SERVER_TOKEN.
LAN and workstations
npx dimo serve listens on every NIC by default. A browser or another desktop on the same LAN uses the printed LAN origin and token. Phone QR pairing needs LAN enabled; a 127.0.0.1 QR is unreachable from the phone. Pairing presets are in the guide Connect to a Host.
Public access terminates TLS on a reverse proxy, then forwards to the Host port. Set DIMO_URL to https://host.example.
Occupancy
One data directory has one Host at a time. When dimo-server occupies the directory, the desktop attaches as a client to that URL. When the desktop occupies the directory, another npx dimo fails or conflicts; stop one process first.
While the Host is offline, control commands fail immediately. Offline cache exists only on paired client UIs.