From fa897e5dfe0a6c4eda5bd828360578ac4cfdeb89 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 18 Jan 2026 07:58:59 +0000 Subject: [PATCH] docs: explain node host use cases --- docs/cli/node.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/cli/node.md b/docs/cli/node.md index 5c05303e7..8433499e3 100644 --- a/docs/cli/node.md +++ b/docs/cli/node.md @@ -10,6 +10,19 @@ read_when: Run a **headless node host** that connects to the Gateway bridge and exposes `system.run` / `system.which` on this machine. +## Why use a node host? + +Use a node host when you want agents to **run commands on other machines** in your +network without installing a full macOS companion app there. + +Common use cases: +- Run commands on remote Linux/Windows boxes (build servers, lab machines, NAS). +- Keep exec **sandboxed** on the gateway, but delegate approved runs to other hosts. +- Provide a lightweight, headless execution target for automation or CI nodes. + +Execution is still guarded by **exec approvals** and per‑agent allowlists on the +node host, so you can keep command access scoped and explicit. + ## Start (foreground) ```bash