Getting Started
What is Node9?Quick StartHow It WorksForecastAgent IntegrationsAccount & Machine
Configuration
ConfigurationPrivacy & Cloud ModeSmart RulesEffective ConfigurationPersistent DecisionsPause & Resume
Protections
Checks ReferenceShieldsSandboxSecurity PostureContent Scanner (DLP)Trusted HostsCanary CredentialsSkill PinningRepository ScanningEgress ControlBadges
Integrations
MCP GatewayMCP ServerPython SDKGoverned Agents
Operations
Mission ControlReportSecurityAgentic Threat CoverageBlast RadiusSessions & Live ActivityRedacting Session HistoryCloud Policy Rules
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 asks for your approval inline, in the agent itself, on Claude Code and GitHub Copilot CLI; elsewhere it shows its own OS dialog.

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
  • 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.

Inline in the agent (default)Local
On Claude Code and GitHub Copilot CLI the review prompt appears inside the agent's own approve/deny flow. Set settings.reviewChannel: "approver" or pass --no-ask to the hook to get node9's OS dialog instead, with "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.