Getting Started
What is Node9?Quick StartHow It Works
Configuration
ConfigurationPrivacy & Cloud ModeSmart Rules
Protections
ShieldsSandboxSecurity PostureContent Scanner (DLP)Trusted Hosts
Integrations
MCP GatewayMCP InterceptorMCP ServerPython SDKGoverned Agents
Operations
Mission ControlReportSecurity
Help
Help & SupportAbout Node9

How It Works · node9 documentation

How It Works

Node9 evaluates commands from top to bottom. The first match wins.

The Golden Rule
Node9 uses an Early Return model. If a command is explicitly allowed by a Sandbox or a Rule, the evaluation stops immediately. It will not trigger the Dangerous Words list.

Phase 1 — Local Fast Path

These checks run synchronously from your merged local config (defaults + global + project). If any fast-path check resolves the call, the pipeline stops here — the cloud is never contacted.

1ignoredTools — immediate allow
If the tool name matches any pattern in policy.ignoredTools, the call is approved instantly with no further checks. Use this for read-only tools (list_*, read_*, grep) that you unconditionally trust.
2Trust session check — allow if active
If the user previously selected "Trust this tool for this session", Node9 skips policy and allows immediately. Trust sessions are stored in ~/.node9/trust.json with an expiry time.
3Local policy evaluation
Node9 evaluates the call against the merged policy in this order:
  1. smartRules — evaluated first, directly on the raw JSON args (no tokenization needed). Includes built-in rules (force push, SQL without WHERE, curl-pipe-shell) plus any active Shield rules and your custom rules. Verdict can be allow, review, or block. First matching rule wins.
  2. toolInspection — if the tool maps to a parameter key (e.g. bash → "command"), extract the command string for deeper analysis.
  3. sandboxPaths — if all path tokens in the call are inside a sandboxed directory, allow immediately.
  4. dangerousWords — if the command contains a keyword from this list, flag for review.
Result is allow (pipeline stops), block (hard deny, no prompt), or review (continues to Phase 2).
4Persistent decision check — user's saved choices
If the user previously chose "Always Allow" or "Always Deny" for this tool, that choice is applied from ~/.node9/decisions.json. Overrides the policy result.

What if the AI tries to run rm -rf src/?

No smart rule explicitly allows it, and src/ is not in any sandbox path. Node9 flags it for review and shows a Native OS popup asking for your approval.

Example Trace: AI tries to run rm -rf node_modules/
  1. 1. Ignored Tools: Is bash in the ignored list?
    ↳ No. (Move to next step)
  2. 2. Smart Rules: Does any rule match this command?
    ↳ Yes! The built-in allow-rm-safe-paths rule allows rm on common build/cache dirs like **/node_modules/**.
    🏁 EVALUATION STOPS HERE. Command is APPROVED.
  3. 3. Dangerous Words: Check if "rm" is a dangerous word.
    ↳ Skipped. The smart rule already approved it.

Phase 2 — The Multi-Channel Race

Only reached if Phase 1 produced a review verdict and approvers.cloud is true with a valid API key. The local config is not re-evaluated here — cloud policy is enforced by the backend independently.

5initNode9SaaS — backend policy check
Node9 sends the tool call to the Node9 backend. The backend evaluates the workspace's Cloud Policy Studio rules (the policies you configure in the dashboard).
  • If the backend immediately approves or denies — done. Pipeline ends.
  • If the backend marks it as pending — a Slack message is sent and the proxy waits.
  • If the backend is unreachable — falls back to local approvers with a warning.
6Approval race — cloud vs local approvers
While waiting for a human response, Node9 runs all enabled approvers in parallel — whichever resolves first wins. The losers are cancelled and notified.
  • cloud — polls Mission Control for an admin decision (Slack button or dashboard)
  • native — shows an OS dialog on the developer's machine
  • browser — routes to the local Node9 browser dashboard (localhost:7391)
  • terminal — interactive y/n prompt in the CLI
If remoteApprovalOnly is set by the backend (governance lock), local approvers are suppressed — only a cloud admin can approve.
7Result is returned and logged
The final approved/denied result is returned to the agent. Every decision — regardless of which phase resolved it — is written to ~/.node9/audit.log and (when cloud is enabled) recorded in Mission Control.

If a command reaches the end of the waterfall and is flagged as dangerous, Node9 pauses the AI and races multiple approval channels simultaneously.

Native OS PopupLocal
A secure OS-level dialog box appears on your screen. You can click "Allow", "Block", or "Always Allow".
Terminal PromptFallback
If you are looking at the CLI, an interactive [y/N] prompt appears directly in your terminal.
Mission ControlCloud
If connected, the request streams to the Cloud Dashboard where a Team Admin can approve it (e.g., via Slack).

Whichever channel you approve/deny through first wins. Node9 immediately cancels the others and passes your decision back to the waiting AI agent.