The Node

The Node is the OCC runtime that lives on the user's machine. It is a single application that opens a web interface in the browser, loads a local Qwen language model, retrieves knowledge from the broker, runs the multi-agent deliberation, and exposes everything through a chat-style UI.

This page covers what the Node is in operational terms: the interface, the modes, the commands, the settings, and how it connects to the rest of the network. Installation and first-run setup are described in Getting started.

The web interface

When the Node is running, the browser tab shows a web app at http://localhost:7891. The layout has three persistent regions plus a settings modal.

Sidebar (left)

• OCC wordmark at the top.
• New Chat button — starts a fresh conversation.
• Search box — filters past chats by title.
• Chat list — scrollable, grouped by recency. Hover any title to reveal a delete button.
• Three buttons at the bottom: Scout, Forge, Settings.

Each chat opens to a single message thread; conversations are saved automatically.

Chat panel (center)

• Header — chat title, a provider badge (local or openrouter), an optional GPU usage indicator, and two tabs:
  • Chat — the active conversation.
  • Broker Logs — a terminal-style live view of what the broker agent is doing (peer registrations, retrieval calls, deliberation steps). Useful for debugging or curiosity.
• Message list — alternating user and assistant bubbles, each with copy buttons. Assistant messages carry a routing badge (see below) and may also carry source citations (clickable pack/file references) and tool indicators (e.g. WEB, URL, PDF, VERIFY, CATALOG).
• Input row — textarea, attachment paperclip, send button.
  • Enter sends. Shift+Enter inserts a newline.
  • Paperclip / drag-and-drop attaches files. Supported types: images, audio, PDFs, Word documents, Excel spreadsheets, plain text, markdown, common code files, JSON, YAML, TOML, shell scripts, CSVs.
  • A context bar appears below the input when the conversation approaches the model's context limit, showing how much room is left.

When you attach a binary file, the Node automatically stays in "chat mode" for the rest of the conversation so atomic tools (read_pdf, read_xlsx, transcribe_audio, …) remain reachable for follow-up questions. See Tools.

Run banner (top)

While a Forge build is running, a persistent banner appears at the top of the app with elapsed time, a View button, and a Stop button. You can switch tabs or open another chat without losing track of the build.

Settings modal

Opened from the Settings button in the sidebar. Covered in detail in Settings below.

Routing badges

After every assistant reply, a small colored badge labels the path the engine took. The five possible labels:

• chat — the message was conversational or tool-driven; no retrieval was performed. Shown for greetings, simple meta-questions ("who are you"), file handling, code execution, and web tool calls.
• server + local — full three-stage deliberation against the shared community packs on the broker; the Critic ran locally. The default for knowledge questions.
• local · private — full three-stage deliberation against only your own private Forge packs on disk. The broker is not consulted. Shown when Knowledge Source in Settings is set to "Local only".
• offline · no knowledge — the broker was unreachable, so OCC answered using only the base model's training (no curated grounding). The graceful-degradation path — the answer is not backed by a verified source.
• network — full deliberation, with the Critic role delegated to a peer Node on the OCC network. Shown when a stronger peer is online and the question benefits from a more powerful reviewer. The exchange is end-to-end encrypted; the broker only routes ciphertext.

Modes

The Node operates in two top-level modes, decided per message:

• Chat mode is for casual interaction: greetings, meta-questions, short exchanges that don't benefit from the multi-agent pipeline. Chat mode runs against the local model with a small set of agentic tools available (see Tools).
• Deliberate mode runs the full retrieval-and-deliberation pipeline described in How OCC works: decompose, search, retrieve, Expert, Critic, Synthesizer.

A small classifier picks the mode automatically. Internally the classifier resolves to one of four categories — chitchat, tools, knowledge (= deliberate), skill — but the user only sees the resulting badge. Pure greetings get a fast path that bypasses every overhead.

A user who wants to override and force network deliberation can prefix a message with ! — for example, ! summarize the latest research on Roman concrete.

Local-only vs server packs

A separate axis controls which packs the Node draws from:

• Server packs (default). Retrieval happens against the broker's catalog of community-approved packs.
• Local packs only. Retrieval happens against packs installed on the user's machine. The broker is not consulted. Useful for private packs containing personal or organizational data — see Forge for how to build them.

The toggle is in Settings → Knowledge Source, or via the /local on and /local off slash commands.

Network mode (peer Critic)

When deliberate mode runs, the Node may delegate the Critic step to a more capable peer Node on the network. This happens when:

• The Node is connected to the broker.
• A peer with stronger hardware (a higher tier) is currently registered.

The peer Critic exchange is end-to-end encrypted; the broker routes ciphertext only. See Multi-agent deliberation for the mechanics and Security for the threat model.

Slash commands

Typing / in the chat input opens an auto-complete tooltip with the available commands. The complete list:

Command	Effect
/clear	Clear the conversation history and reset context.
/status	Show current model, tier, context size, provider, loaded packs, and peer count.
/packs	List the loaded packs and their domains.
/peers	Show active peer Nodes registered on the broker, with hardware tier and VRAM.
/local on / off	Switch between local-only packs and server packs.
/load	Load the local model into VRAM (warm up before a session).
/unload	Unload the local model from VRAM (free GPU memory while keeping OCC running).
/openrouter on / off	Switch Node responses between the local Qwen model and a Qwen variant on OpenRouter.
/ollama	Toggle raw-Ollama mode. When ON, OCC bypasses its framework entirely — no classifier, no skills, no retrieval, no tools, no system prompt. Useful for comparing raw-model behavior against the OCC stack.
/help or /?	Show inline help.
! <query>	Force network deliberation for a single message.

These are equivalent to operations available in the settings UI; they exist so experienced users don't have to leave the keyboard.

Settings

Open the modal from the Settings button in the sidebar. Five sections, in order:

Node Info

Read-only metadata: model in use, hardware tier, detected VRAM, broker URL.

Knowledge Source

A two-sided toggle that decides where retrieval reads from:

• OCC Server (left, default) — fetch from the community packs on the broker.
• Local only (right) — fetch only from your private packs in expert-packs/. The broker is not contacted.

Below the toggle is a list of every pack currently on disk, each with its own enable/disable switch. You can selectively activate a subset of your local packs. Three convenience buttons:

• Load ALL — enables every pack on disk.
• Unload ALL — disables every pack (local retrieval will return nothing until you re-enable some).
• Reindex — rebuilds the local full-text search index over all packs. Forge and Lint already do this automatically for the pack they touch; use this button only after manually adding or moving pack folders.

OpenRouter

OpenRouter is a marketplace of cloud models accessed through a single API key. OCC uses OpenRouter in two distinct places, and the Settings panel makes the distinction explicit:

• Forge always uses OpenRouter when a key is set. Building a pack benefits from the strongest possible model because you ingest knowledge once and query it forever. Forge runs on top-tier proprietary models (GPT-5, GPT-5 Mini, Claude Sonnet 4.6) selected from inside Forge itself. Forge will not run without an API key.

• Node responses use OpenRouter only when the toggle below is ON. Off by default — the Node uses the local Qwen model matched to your hardware tier. Flip it on if you want chat answers to come from a larger Qwen variant running on OpenRouter (e.g. Qwen up to ~35B) — faster on slow hardware, more capable, a few cents per question. The Node is and remains Qwen-only; top-tier proprietary models are not used for chat responses.

Getting an OpenRouter API key:

1. Open openrouter.ai/keys (link in the Settings panel).
2. Sign up (Google login is fine), top up a few dollars of credit.
3. Click Create key, copy the sk-or-v1-... string.
4. Paste it into the API Key field in OCC Settings and click Save.

The key is stored locally in your OCC config. It is never sent anywhere except directly to OpenRouter for the calls you trigger.

The Model dropdown below the key selects which OpenRouter Qwen variant the Node uses when its OpenRouter toggle is on. Forge has its own per-call model picker for choosing among top-tier models.

Software — Update to latest

A single Update to latest button pulls the newest OCC version from the official repository, reinstalls dependencies, and restarts the Node automatically. Manual fallback: git pull followed by pip install -r node/requirements.txt.

Data — Clear all chats

A destructive button that wipes every saved conversation from disk. The chats are stored in a single local file inside the OCC folder (typically .occ_chats.json). This action cannot be undone — there is no recycle bin.

Background services

Two services run alongside the chat server:

• Broker agent. A WebSocket connection to the broker that registers the Node with its tier, VRAM, and public key. The agent keeps the connection alive with periodic pings, exchanges encrypted Critic payloads when peer reviews are routed, and re-establishes the connection on transient failures. Its live output is shown in the Broker Logs tab of the chat header.
• Model warmup. On startup, the Node sends a keepalive ping to Ollama that loads the configured Qwen model into VRAM and pins it there. This eliminates the multi-second cold-start delay on the first query of a session.

Filesystem layout

The Node uses a small set of folders inside its install directory:

• expert-packs/ — every subfolder is a local pack. Read by the Node and made available via local-only mode.
• workspace/ — sandboxed working directory for code execution and writable files. read_file, write_file, list_files, and run_code all live here.
• upload/ — landing spot for files attached via the paperclip. read_pdf, read_docx, read_xlsx, and transcribe_audio read from here.

Plus two persistent files:

• ~/.occ/config.json — OpenRouter API key, model preference, local-mode toggle, any user-set overrides. Lives in the user's home directory.
• .occ_chats.json — saved conversations. Lives at the root of the OCC installation directory.

Both are local-only, never uploaded, and gitignored at the repository level. Neither contains pack content. Neither is shared with any other party.

Network identity

On first run, the Node generates an X25519 keypair using the standard Curve25519 elliptic curve. The public key is shared with the broker as part of registration; the private key never leaves the machine. Peer Critic exchanges use this keypair for an ECDH handshake to derive an AES-GCM session key, which encrypts the actual payload.

See Security for how this fits into the threat model.