Headless Navi Nodes — Future Architecture Sketch

Status: Research / deferred. Not in active development. Date: 2026-05-24

Problem

Navi currently runs all tools (terminal, filesystem, code_exec, ssh_exec) on the same machine as the backend server. Users who want Navi to manage their local dev machine must either:

1. Run the entire Navi backend locally (heavy, requires PostgreSQL).
2. Use ssh_exec to loopback to localhost (clunky, requires local sshd).

The original idea — a "terminal client" that lets the browser execute commands on the user's local machine — was explored and rejected.

Rejected Approach: Browser-Based Client-Side Execution

Why it was considered

A browser-based client could theoretically receive a terminal command from the server, run it locally via a companion app or extension, and return stdout.

Why it was rejected

1. Sandbox impossibility. Browsers cannot spawn local shells. A companion (Electron / Tauri / browser extension + native messaging host) is required, which is no longer a "web client".
2. Agent loop blocking. Agent.run_stream assumes tools are synchronous await tool.execute() calls inside a single Python process. A remote tool that waits for a browser response would freeze the entire agent loop or require a full async-state-machine refactor.
3. C2 / trust model. The server instructing the client to execute arbitrary commands is a command-and-control pattern. Authentication, authorization, and sandboxing of the client-side executor become critical and complex.
4. Device ambiguity. If a user has Navi open on desktop and mobile, which device executes terminal("npm install")? Requires device registry, affinity, and explicit routing.
5. Maintenance burden. Supporting three platforms (Linux, macOS, Windows) with installable companion software is unsustainable for a personal-assistant project.

Conclusion: Browser-based client-side execution is architecturally incompatible with Navi's current synchronous tool loop and operationally too expensive.

Preferred Approach: Headless Navi Nodes (Swarm)

Concept

A headless Navi node is a lightweight instance of the Navi backend (FastAPI + agent loop) without a web client. It runs on the target machine (e.g. a user's dev laptop, a VPS, a home server) and connects back to a central Navi server.

• The central server handles user-facing sessions, web client, and orchestration.
• Headless nodes handle local tool execution on their respective hosts.
• Both share a common PostgreSQL database for session persistence and scheduler state.
• Communication is via outbound WebSocket from node to central server (avoids NAT issues).

High-level diagram

┌──────────────┐      WS/HTTP       ┌──────────────┐
│   Browser    │◄───────────────────►│   Central    │
│  (web client)│                     │ Navi Server  │
└──────────────┘                     └──────┬───────┘
                                            │
                                            │ WS outbound
                                            │ (nodes register here)
                                            │
        ┌───────────────────────────────────┼───────────────────────────────────┐
        │                                   │                                   │
        ▼                                   ▼                                   ▼
 ┌──────────────┐                ┌──────────────┐                ┌──────────────┐
 │  Headless    │                │  Headless    │                │  Headless    │
 │  Node A      │                │  Node B      │                │  Node C      │
 │  (dev laptop)│                │  (home NAS)  │                │  (VPS)       │
 └──────┬───────┘                └──────┬───────┘                └──────┬───────┘
        │                              │                              │
        ▼ local shell                  ▼ local shell                  ▼ local shell

Advantages

• No agent loop changes. terminal, filesystem, code_exec remain synchronous Python tools inside the node's process.
• No browser sandbox issues. Tools run in a real OS process on the target machine.
• NAT-friendly. Nodes initiate outbound connections; no reverse tunnels or port forwarding needed.
• Composable. A user can attach as many machines as needed. Central server routes tasks to the appropriate node.

Open Questions (To Be Solved Before Implementation)

1. Shared Database Partitioning

If all nodes share one PostgreSQL database:

• Scheduler race. Multiple nodes polling recalls will try to execute the same scheduled task. Needs claimed_by column or a leader-election mechanism per recall.
• Session concurrent edits. Two nodes appending to the same session's messages array could overwrite each other. Needs row-level locking or instance_id partitioning.
• Memory extractor storm. process_stale_sessions on every node would duplicate embedding work. Needs instance_id gating so only the central server or a designated node runs background workers.

Direction: Tag every row with instance_id (central = main). Nodes only read/write rows assigned to them. The scheduler table gets a claimed_by atomic UPDATE.

2. Tool Routing in the Agent

The agent on the central server must know that terminal for profile server_admin should run on Node B, not locally.

Options:

• Profile-level node affinity. Profile server_admin has node_id: "home-nas". All tools in that profile execute on that node.
• Remote tool proxy. The central registry has proxy tools (remote_terminal, remote_filesystem) that forward calls to the node's REST/WebSocket API.
• Subagent on node. spawn_agent spawns the subagent on a remote node via the node's API instead of locally.

3. Headless Node Packaging

• Docker: Easy to ship, but terminal and filesystem operate inside the container by default. Access to the host requires --privileged, --pid host, or explicit volume mounts, which weakens isolation.
• Systemd service / bare process: Full host access natively, but harder to install and update across platforms.

Direction: Provide both: Docker for sandboxed/isolated tasks, bare-metal install script for full host management.

4. Authentication

Nodes must prove identity to the central server.

• Shared secret (NODE_API_KEY) in .env.
• mTLS (client certificates).
• JWT registration flow (node registers once, receives token).

5. Communication Protocol

• WebSocket outbound (ws://central.navi/ws/nodes/{node_id}) for real-time task streaming.
• REST fallback for nodes behind restrictive proxies.
• Reuse the existing event schema (stream_start, tool_started, stream_delta, stream_end) so the central server can forward node events to the browser client unchanged.

6. Lifecycle

• Node startup: register capabilities (available tools, OS, profiles) with central server.
• Heartbeat: ping every N seconds; central server marks node offline if missed.
• Graceful shutdown: close WS, release claimed recalls.

Decision Log

Next Steps (When Prioritised)

1. Design instance_id database partitioning for sessions, recalls, and content.
2. Add /ws/nodes/{node_id} endpoint to central server for node registration and task streaming.
3. Define node-to-central auth mechanism (API key or mTLS).
4. Build minimal headless node package (Dockerfile + .env template).
5. Implement remote tool routing in ToolRegistry or as proxy tools.
6. Add node heartbeat and offline detection to AgentSessionOrchestrator.