Remote node host (system.run)

Use a node host when your Gateway runs on one machine and you want commands to execute on another. The model still talks to the gateway; the gateway forwards exec calls to the node host when host=node is selected.

Approval note:

• Approval-backed node runs bind exact request context. The exec path prepares a canonical systemRunPlan before approval; once granted, the gateway forwards that stored plan, not any later caller-edited command/cwd/session fields, and re-validates the working directory before running.
• For direct shell/runtime file executions, Apus also best-effort binds one concrete local file operand and denies the run if that file changes before execution.
• If Apus cannot identify exactly one concrete local file for an interpreter/runtime command, approval-backed execution is denied instead of pretending full runtime coverage. Use sandboxing, separate hosts, or an explicit trusted allowlist/full workflow for broader interpreter semantics.

Gateway deployments that cannot host nodes

A Gateway can remain healthy for browser users while node hosting is unavailable. Run apus doctor on the Gateway before onboarding nodes, and check these preconditions:

• Machine authentication: Tailscale identity headers do not authenticate node-role connections. In gateway.auth.mode: "trusted-proxy", a new node also cannot supply the proxy's user identity headers. To use a shared token, switch to token mode and configure gateway.auth.token with a SecretRef; trusted-proxy mode rejects mixed token configuration. A trusted-proxy Gateway can use gateway.auth.password only for clean loopback/direct callers. See trusted-proxy mixed token configuration.
• Node onboarding URL: With only the default gateway.bind: "loopback" and no advertised endpoint, apus devices join-code reports that the Gateway is only bound to loopback and recommends gateway.publicOrigin as the primary fix. For public HTTPS ingress, set it to the proxy's reachable origin. Existing Tailscale Serve, gateway.remote.url, bind-derived addresses, and the pairing-specific plugins.entries.device-pair.config.publicUrl override retain their precedence; publicOrigin supplies the loopback fallback. Remote join URLs require TLS; enabling LAN bind alone does not enable plaintext remote join URLs. Explicitly configured loopback endpoints can produce HTTP join URLs, but the joining machine must be able to reach that loopback endpoint, for example through a local tunnel. Plaintext LAN pairing can use a setup code directly.
• Node onboarding support: Join-code creation and /j redemption are core Gateway operations. They do not require enabling the device-pair plugin, even though its retained publicUrl configuration field can supply an endpoint. See Join codes for the printed npx -y apus connect <url> --service --session-host command and the command-only alternative.
• Device session runtime: Paired-device runners support the embedded Apus runtime and explicitly authorized Codex remote-exec; ACPX routes cannot dispatch to a paired device. Codex requires codex.exec-server.stdio.v1 in gateway.nodes.commands.allow plus its normal pairing and invocation approvals. Runtime policy belongs on provider/model routes, not the ignored whole-agent runtime keys. Multi-agent rosters must also set agents.ownership: "explicit". See Codex paired-device placement and runtime policy.
• Edge routing: When a reverse proxy or access edge fronts the Gateway, the node must satisfy edge auth on the join request, its main Gateway WebSocket, and the worker WebSocket. Keep WebSocket upgrade enabled for /__apus__/worker. You can instead exempt /j/* and /__apus__/worker from edge identity auth because both routes enforce their own short-lived credentials. See worker protocol.

For a Cloudflare Access-fronted Gateway:

1. In Cloudflare Zero Trust, create an Access service token. Copy its Client ID and Client Secret when Cloudflare displays them.

2. Add a Service Auth policy that accepts the token on the Access application protecting the Gateway. If /j/* and /__apus__/worker are separate Access applications, add the same policy to both.

3. On the node, provide the conventional environment fallback and connect:

   export CF_ACCESS_CLIENT_ID="<client-id>"
   export CF_ACCESS_CLIENT_SECRET="<client-secret>"
   apus connect https://gateway.example/j/<code> --service
   

The canonical node connection keys are gateway.cloudflareAccess.clientId and gateway.cloudflareAccess.clientSecret; both accept SecretInput values. The environment fallback above persists those keys as env SecretRefs, not copied plaintext. For installed nodes, Apus stores the environment values in the managed service environment file rather than inline in launchd, systemd, or Task Scheduler definitions. Resolved values are bound to the configured Gateway origin and are not followed across redirects. Apus rejects the pair before resolution on plaintext http:// or ws:// routes; credential-free loopback and private-network plaintext behavior is unchanged.

Start a node host (foreground)

On the node machine:

apus node run --host <gateway-host> --port 18789 --display-name "Build Node"

For one-paste setup, create a Node host setup link from the Control UI Devices page, then run its copyable command on the node machine:

apus node run --pair "oc-pair://<setup-code>"

The link is single-use and expires after 10 minutes. It supplies the endpoint, bootstrap token, TLS mode, and certificate pin when available. Explicit gateway flags override the corresponding --pair values. Administrator-minted bootstrap enrollment approves the device and its first declared command surface, including system.run and system.which when declared. Later command, capability, or permission expansion still creates an approval request. Gateway command policy and the node host's exec approvals still apply. Local exec approvals default to full with ask: "off"; configure them before using the link if that access is too broad. See Node pairing.

node run also accepts --pair, --context-path (Gateway WS context path), --tls, --tls-fingerprint <sha256>, and --node-id (override the legacy client instance ID; this does not reset pairing). On macOS, pass --share-installed-apps to advertise device.apps; sharing is off by default. Use --no-share-installed-apps to disable a previously saved opt-in.

Pass --session-host to enable worker hosting for this foreground process without changing the saved preference. Automatic restarts preserve this choice.

Remote gateway via SSH tunnel (loopback bind)

If the Gateway binds to loopback (gateway.bind=loopback, default in local mode), remote node hosts cannot connect directly. Create an SSH tunnel and point the node host at the local end of the tunnel.

Example (node host -> gateway host):

# Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# Terminal B: export the gateway token and connect through the tunnel
export APUS_GATEWAY_TOKEN="<gateway-token>"
apus node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

Notes:

• apus node run supports token or password auth.
• Env vars are preferred: APUS_GATEWAY_TOKEN / APUS_GATEWAY_PASSWORD.
• Config fallback is gateway.auth.token / gateway.auth.password.
• In local mode, node host intentionally ignores gateway.remote.token / gateway.remote.password.
• In remote mode, gateway.remote.token / gateway.remote.password are eligible per remote precedence rules.
• If active local gateway.auth.* SecretRefs are configured but unresolved, node-host auth fails closed.
• Node-host auth resolution only honors APUS_GATEWAY_* env vars.

Restrict the node command surface

Pass --commands <ids> to apus node run, apus node install, or apus connect to advertise only an explicit comma-separated list of exact command IDs. For example, a Session Share node can publish sessions without exposing execution or other machine capabilities:

apus connect <join-url> --service \
  --commands apus.sessions.list.v1,apus.sessions.read.v1

The flag is repeatable. The allowlist is saved in the node's durable machine state, including for installed services; omitting it on a later start keeps the saved list. The node advertises only commands that are both available and allowlisted, with only their required capabilities. Startup fails if no requested command is available. The Gateway pairing approval shows exactly the declared commands; Gateway command policy still applies to invocation.

An explicit allowlist also disables computer use, skill scanning and publication, plugin-tool publication, MCP servers, and worker hosting. An allowlist does not enable a disabled plugin or make an unavailable command available.

Restore the full default surface with apus node run --all-commands in the foreground or apus node install --force --all-commands for an installed service. When enrolling with apus connect, add --all-commands and optionally --service. This durably removes the saved allowlist and replaces the service's --commands arguments. Do not combine --all-commands with --commands.

Start a node host (service)

apus node install --host <gateway-host> --port 18789 --display-name "Build Node"
apus node start
apus node restart

node install also accepts --context-path, --tls, --tls-fingerprint, --node-id (legacy client instance ID only), --share-installed-apps / --no-share-installed-apps, --runtime <node|bun> (default: node), and --force to reinstall. Bun requires version 1.4+ with WAL-reset-safe node:sqlite and is an explicit opt-in; Node remains recommended. node status, node stop, and node uninstall are also available.

Node shutdown waits for plugin availability watchers and active computer executions to finish cleanup, and reports failures from those cleanup operations. If a command reports Node disconnect cleanup failed, reconnect the node to retry disconnect cleanup before sending another command.

Session-host workspace permissions

A node started with --session-host checks workspace staging before advertising session capacity. On Unix, the state directory (APUS_STATE_DIR, or ~/.apus) and its canonical ancestors must satisfy the filesystem owner's checks. Group- or world-writable ancestors without sticky protection prevent session hosting, even when the node-host directory itself is private.

The node log and environments.list identify the offending directory and the remediation: run chmod go-w '<reported-path>' on the node, then restart the node host. Review shared-directory permissions before changing them; alternatively, move node state under a private directory. Apus does not change ancestor permissions or bypass staging checks. A trusted sticky system temporary directory remains supported.

A session-host failure does not disconnect the node or disable its desktop and other available commands. environments.list keeps a connected node available, reports sessionHost: false and the hosting diagnostic, and refuses session placement until the hosting problem is repaired.

Disabled-host reasons are published only when the Gateway advertises node-worker-host-diagnostics-v1. Older Gateways still receive disabled hosting; the node log retains the reason. Workspace transfers also report the same remediation if permissions change after startup.

Automatic node updates

Packaged headless nodes check for updates hourly by default, in both foreground and service mode. They prepare a separate runtime, wait until all node work is idle, then restart and reconnect with the same identity, pairing, and launch options. A node update does not replace the global CLI package or a co-located Gateway. Automatic activations are at least 12 hours apart, and busy work can defer an update indefinitely.

Set nodeHost.autoUpdate.enabled: false on the node to opt out. The shared update.checkOnStart: false and APUS_NO_AUTO_UPDATE=1 opt-outs also apply. Source checkouts, native app nodes, private workers, dev, and extended-stable installs do not auto-apply. Releases requiring database migrations defer to the normal update workflow. See Headless node updates for the idle-work rules and configuration.

Pair + name

On the Gateway host, approve the device request:

apus devices list
apus devices approve <deviceRequestId>

If the node retries with changed auth details, re-run apus devices list and approve the current requestId.

The node keeps reconnecting while device approval is pending, with exponential backoff capped at 30 seconds. After approval, its next reconnect creates a separate command-surface request. On the Gateway:

apus nodes pending
apus nodes approve <nodeRequestId>
apus nodes describe --node <id|name|ip>

If an older client already reports that reconnect is paused, restart the installed node with apus node restart, or stop and rerun its foreground apus node run command once.

The device and node request IDs are distinct. An initial unapproved surface has no effective commands. SSH-verified and bootstrap enrollment can approve the first surface automatically; trusted-network device approval alone does not. Later expansions need approval, while previously approved commands that remain declared and allowed can still run. Gateway command policy and node-local exec approvals remain separate gates.

Naming options:

• --display-name on apus node run / apus node install (persists in the shared nodeHost.config SQLite machine-state value alongside the client instance ID and Gateway connection metadata).
• apus nodes rename --node <id|name|ip> --name "Build Node" (gateway override).

Headless identity state

The headless node keeps three separate state records in shared SQLite:

• ~/.apus/state/apus.sqlite (config_machine_state, key nodeHost.config): the client instance ID, display name, and Gateway connection metadata.
• ~/.apus/state/apus.sqlite (device_identities, key primary): the signed device keypair and derived cryptographic device ID.
• ~/.apus/state/apus.sqlite (device_auth_tokens): paired device auth tokens keyed by cryptographic device ID and role.

For a signed node, the Gateway uses the cryptographic device ID for pairing and node routing. The client instance ID is only connection metadata. Changing --node-id or migrating a retired node.json therefore does not reset pairing. See Identity and pairing state for the supported revoke-and-re-pair flow and upgrade notes.

Retired identity/device.json and identity/device-auth.json files are Doctor-owned migration inputs. Stop the node host and run apus doctor --fix; Doctor imports and verifies their rows in SQLite before removing the old files.

The headless node and macOS app worker check this state before preparing capabilities. Pending device auth, exec approvals, or a missing canonical identity with retired identity data requires Doctor; startup preserves the inputs and does not create replacement keys or import execution policy. A valid canonical identity keeps precedence over stale identity/device.json data.

System commands (node host / mac node)

The macOS node and headless node host both expose system.run.prepare, system.run, system.which, and system.execApprovals.get/set; the macOS node also exposes system.notify.

Examples:

apus nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
apus nodes invoke --node <idOrNameOrIp> --command system.which --params '{"bins":["git"]}'

Notes:

• system.run returns stdout/stderr/exit code in the payload.
• Shell execution goes through the exec tool with host=node; the separate nodes.run execution path was removed in 2026.3.31. nodes remains the direct-RPC surface for explicit node commands.
• nodes invoke does not expose system.run or system.run.prepare; those stay on the exec path only.
• The exec path reads the node policy and prepares a canonical systemRunPlan. Full/off execution resolves working-directory aliases without adding approval-only script checks. When caller or node policy requires approval binding, stricter path and script checks remain in place. Once an approval is granted, the gateway forwards that stored plan, not any later caller-edited command/cwd/session fields.
• system.notify respects notification permission state on the macOS app; supports --priority <passive|active|timeSensitive> and --delivery <system|overlay|auto>.
• Unrecognized node platform / deviceFamily metadata uses a conservative default allowlist that excludes system.run and system.which. If you intentionally need those commands for an unknown platform, add them explicitly via gateway.nodes.commands.allow.
• A system.run request supports cwd, an env map, timeoutMs, and needsScreenRecording — these are fields of the request payload carried on the exec path (see above), not nodes invoke CLI flags.
• For shell wrappers (bash|sh|zsh ... -c/-lc), request-scoped env values are reduced to an explicit allowlist (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
• For allow-always decisions in allowlist mode, known dispatch wrappers (env, flock, nice, nohup, stdbuf, timeout) persist inner executable paths instead of wrapper paths. If unwrapping is not safe, no allowlist entry is persisted automatically.
• On Windows node hosts in allowlist mode, shell-wrapper runs via cmd.exe /c require approval (allowlist entry alone does not auto-allow the wrapper form).
• Node hosts ignore PATH overrides in the env object and strip a large, maintained set of interpreter/shell startup variables (for example NODE_OPTIONS, PYTHONPATH, BASH_ENV, DYLD_*, LD_*) before running a command. If you need extra PATH entries, configure the node host service environment (or install tools in standard locations) instead of passing PATH via env.
• On macOS node mode, system.run is gated by exec approvals in the macOS app (Settings → Exec approvals). Ask/allowlist/full behave the same as the headless node host; denied prompts return SYSTEM_RUN_DENIED.
• On headless node host, system.run is gated by the local SQLite exec approvals row; on macOS specifically, see the exec-host routing env vars under Headless node host below.

Headless node host (cross-platform)

Apus can run a headless node host (no UI) that connects to the Gateway WebSocket and exposes system.run / system.which. This is useful on Linux/Windows or for running a minimal node alongside a server.

Start it:

apus node run --host <gateway-host> --port 18789

Notes:

• Device pairing and command-surface approval are still required; follow Pair + name through both stages.
• Client instance metadata, signed device identity, and pairing auth use separate state records; see Headless identity state.
• Exec approvals are enforced locally via ~/.apus/state/apus.sqlite#exec_approvals_config (see Exec approvals).
• On macOS, the headless node host executes system.run locally by default. Set APUS_NODE_EXEC_HOST=app to require the companion app exec host, with no local fallback. APUS_NODE_EXEC_FALLBACK does not change current routing.
• Add --tls / --tls-fingerprint when the Gateway WS uses TLS.

Mac node mode

• The macOS menubar app connects to the Gateway WS server as a node (so apus nodes … works against this Mac).
• In remote mode, the app opens an SSH tunnel for the Gateway port and connects to localhost.