norax

<div align="center"> # Norax **A self-hosted AI agent runtime built to preserve state, verify tool work, and resume.** [](LICENSE) [](https://www.python.org/) [](https://github.com/clarboncy/norax) [Quick Start](#quick-start) · [Why Norax](#why-norax) · [Features](#features) · [Architecture](#architecture) · [Acknowledgments](#acknowledgments) </div> --- ## The problem Every AI agent demo works for 5 minutes. Then reality hits: - The agent **forgets** what it was doing after a few tool calls - It **loops** — repeating the same failed action or spinning in text without calling tools - It **lies** — claims success without verifying anything actually worked - When you restart it, the task is **gone** — no way to resume - Your memory, personality, and history live on **someone else's server** Norax addresses these failure modes with durable state, bounded tool loops, explicit mutation verification, and tamper-evident operational evidence. ## Why Norax Norax is a self-hosted AI agent runtime built for **long-running, real work**. It runs on your machine, uses configured local or remote models, and stores its runtime memory on your disk. Checkpointed work can be resumed when the underlying state is intact; model output and external side effects remain fallible. ```bash git clone https://github.com/clarboncy/norax.git cd norax bash setup.sh ``` That's it. Norax is live at `http://127.0.0.1:8822` with a full chat dashboard, memory system, and tool loop. ## Features | Feature | What it means | |:--------|:-------------| | **Durable task state** | Checkpointed goals, constraints, facts, blockers, and verification status are designed to survive compaction, model swaps, and restarts. | | **7-layer memory** | Hot state, semantic facts, procedural skills, episodic records, entity graph, temporal graph, and causal links. Persists across sessions. | | **Loop resistance** | Hard round ceilings, tool-call caps, duplicate detection, no-progress detection, and wall-clock deadlines bound each agent run. | | **Verified execution** | Tool receipts plus target-aware readback checks gate mutation success claims. Some external outcomes cannot be proven locally and remain explicitly unverified. | | **Hash-chained evidence** | Operational events form a verifiable hash chain. This is tamper-evident logging, not immutable storage. | | **Dynamic model discovery** | Model-list requests query Ollama through a bounded, 30-second cache; newly pulled models do not require a runtime restart. | | **Multi-provider routing** | Route across Ollama, OpenRouter, and any OpenAI-compatible API. Add providers at runtime without editing config. | | **Web dashboard** | Chat with Norax in your browser before configuring Discord. Markdown rendering, streaming, stop button, model selector. | | **Multi-channel** | Discord, HTTP, and cron ingress. One runtime, multiple interfaces. | | **Owner-controlled safety** | Authenticated sender tiers, risk-gated tools, secret redaction, and filesystem confinement provide operator-controlled boundaries. | | **MCP support** | Connect Model Context Protocol servers for extended tool access. | | **Remote nodes** | Optional remote relay for multi-machine setups. | ## How it compares | Capability | Hosted agents | Coding agents | OpenClaw | **Norax** | |:-----------|:-------------:|:-------------:|:--------:|:---------:| | Self-hosted | — | — | ✓ | ✓ | | Owner controls all data | — | — | ✓ | ✓ | | Durable task state across restarts | — | Partial | — | ✓ | | 7-layer memory system | — | — | Partial | ✓ | | Target-aware mutation verification | — | — | — | ✓ | | Loop prevention (round/tool/time ceilings) | — | Partial | Partial | ✓ | | Tamper-evident hash-chained event log | — | — | — | ✓ | | Dynamic local model discovery | — | — | — | ✓ | | Add API providers at runtime | — | — | ✓ | ✓ | | Web dashboard | — | Partial | ✓ | ✓ | | Multi-channel (Discord, HTTP, cron) | — | — | ✓ | ✓ | | Fully open source (Apache 2.0) | — | — | ✓ | ✓ | | No vendor lock-in | — | — | ✓ | ✓ | ## From inspiration to independence Norax stands on the shoulders of the open-source agent community. The project that most directly shaped our thinking is [OpenClaw](https://github.com/openclaw/openclaw) — Peter Steinberger's open-source personal AI assistant that proved a self-hosted, multi-channel agent could reach hundreds of thousands of users without a walled garden. OpenClaw's core insight — *your context and skills live on your computer, not someone else's server* — is the foundation Norax builds on. We owe credit to OpenClaw and its community for demonstrating that an open, owner-controlled agent is not just possible but preferable. **Where Norax diverges:** | Dimension | OpenClaw | Norax | |:----------|:---------|:------| | Language | TypeScript/Node.js | Python 3.12+ | | Architecture | Gateway + channel plugins | Event-sourced runtime with hot-path brain | | Memory | Session-based with skills | 7-layer: hot state, semantic, procedural, episodic, entity graph, temporal graph, causal links | | Context continuity | Session-scoped | Durable task state across compaction, restarts, and model swaps | | Loop prevention | Tool timeouts | Hard round ceilings, duplicate detection, no-progress detection, wall-clock deadlines | | Verification | Agent-reported | Tool receipts + target-aware readback gates | | Evidence | Logs | Tamper-evident hash chain + Prometheus metrics | | Model routing | Provider configs | Dynamic Ollama discovery + runtime provider API | | Deployment | npm/pnpm workspace | `uv` + systemd user services | | License | Other | Apache 2.0 | Norax is not a fork of OpenClaw. It is a ground-up Python implementation that takes the *philosophy* of owner-controlled agents and pushes it further in three directions: 1. **Reliability over demos.** Every architectural decision optimizes for what happens after the first successful turn — compaction, model failure, tool loops, partial completion, and restart recovery. 2. **Evidence over claims.** Norax does not treat the agent's own success report as proof. Tool receipts and target-aware checks gate mutation claims; outcomes that cannot be observed remain marked unverified. 3. **Memory as infrastructure.** Memory is not a conversation log. It's a 7-layer system with semantic search, procedural skills, episodic records, entity relationships, temporal graphs, causal links, and offline consolidation. ## Quick start ### Guided setup (recommended) ```bash git clone https://github.com/clarboncy/norax.git cd norax bash setup.sh ``` `setup.sh` walks you through owner identity, generates a secure chat token, checks for Ollama, optionally adds API providers and Discord, then starts the runtime and web dashboard. ### Manual setup ```bash git clone https://github.com/clarboncy/norax.git cd norax cp .env.example .env # Edit .env — set NORAX_AGENT_OS_CHAT_TOKEN and NORAX_OWNER_ID uv sync --all-extras uv run --env-file .env python -m norax # runtime on :4101 uv run --env-file .env python agent_os/server.py # dashboard on :8822 ``` Open `http://127.0.0.1:8822` and paste your chat token. No Discord or external account required. ### Talk to Norax before Discord The local web dashboard lets you chat with the full agent — memory, tools, personality — in your browser: 1. Set `NORAX_AGENT_OS_CHAT_TOKEN` to any random string in `.env` 2. Start the runtime: `uv run --env-file .env python -m norax` 3. Start the dashboard: `uv run --env-file .env python agent_os/server.py` 4. Open `http://127.0.0.1:8822` ## Architecture ```text Discord / HTTP / Cron │ ▼ normalized envelope │ ▼ brain hot path (L0-L10) │ ├──► prompt assembly ├──► memory retrieval ├──► policy and risk gates │ ▼ bounded agent/tool loop │ ├──► task-state checkpoint ├──► mutation receipts and readback verification ├──► event + metrics evidence │ ▼ outbound reply ``` ```text norax/ ├── adapter/ # Discord, HTTP, and cron ingress ├── brain/ # hot path, agent loop, planning, verification ├── context/ # rolling context and compaction ├── dispatch/ # tools, policy, sandboxing, and risk gates ├── envelope/ # normalized wire shapes ├── gateway_client/ # provider clients, routing, and budgets ├── memory/ # retrieval, indexing, graphs, and consolidation ├── observability/ # structured logs, metrics, and event evidence ├── prompt/ # deterministic prompt assembly ├── runtime/ # lifecycle, checkpoints, supervision, and recovery ├── safety/ # secret handling and safety boundaries └── soul/ # configurable identity and operating principles ``` ## Configuration Runtime settings live in [`config/runtime.jsonc`](config/runtime.jsonc). Secrets belong in `.env` (gitignored). | Variable | Purpose | |:---------|:--------| | `NORAX_OWNER_ID` | Authoritative owner identity | | `NORAX_OWNER_LABEL` | Owner display name | | `NORAX_OWNER_TIMEZONE` | Owner timezone | | `NORAX_AGENT_OS_CHAT_TOKEN` | Shared secret for the dashboard chat bridge | | `NORAX_DISCORD_TOKEN` | Discord bot token (optional) | | `NORAX_DISCORD_ENABLED` | Enables the Discord adapter | | `NORAX_OLLAMA_URL` | Ollama endpoint (default: `http://127.0.0.1:11434`) | | `NORAX_OPENROUTER_TOKEN` | OpenRouter API token (optional) | | `NORAX_MEMORY_ROOT` | Mutable memory directory | | `NORAX_STATE_DIR` | Events and operational state directory | | `NORAX_LOG_DIR` | Structured log directory | See [`.env.example`](.env.example) for a complete template. ### Dynamic model discovery Norax queries the local Ollama daemon when building the live model list and caches the result for 30 seconds. Pulling a model does not require a runtime restart; refresh the model list after the cache interval. ### Add providers at runtime ```bash curl --request PUT http://127.0.0.1:4101/api/providers/example \ --header "Authorization: Bearer $NORAX_AGENT_OS_CHAT_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "base_url": "https://api.example.com/v1", "api_key": "replace-me", "provider_kind": "openai" }' ``` Keys are stored separately under `~/.config/norax/` with mode `0600`. Discovered models appear immediately in Discord `/model`, `/models`, and the dashboard. ## Development ```bash uv sync --all-extras uv run python scripts/quality_gate.py ``` The gate checks lockfile consistency, lint/format, the configured typecheck surface, bytecode compilation, publication/secrets/memory policy, structural end-to-end wiring, unit coverage, and acceptance tests. Host desktop smoke tests remain separate because they require a real interactive session and optional system dependencies. ## Deployment User-level systemd deployment is documented in [`docs/deploy.md`](docs/deploy.md). Runtime data defaults to: ```text ~/.local/share/norax/memory/ ~/.local/state/norax/ ~/.local/state/norax/logs/ ``` ## Security - Keep HTTP and dashboard on loopback unless token auth is configured - Treat MCP servers and remote nodes as privileged extensions - Review tool allowlists and filesystem roots before enabling external access - Rotate any credential that has appeared in logs, shell history, or git history - Report vulnerabilities privately via GitHub Security Advisories ## Documentation - [`architecture/norax_core.md`](architecture/norax_core.md) — architecture and invariants - [`docs/deploy.md`](docs/deploy.md) — systemd deployment and operations - [`docs/metrics.md`](docs/metrics.md) — Prometheus metrics - [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution and validation workflow - [`SECURITY.md`](SECURITY.md) — vulnerability reporting ## Acknowledgments Norax would not exist without the open-source agent community. - **[OpenClaw](https://github.com/openclaw/openclaw)** — Peter Steinberger and the OpenClaw Foundation proved that a self-hosted, owner-controlled, multi-channel AI agent could reach hundreds of thousands of users. The core philosophy — *your context lives on your computer, not a walled garden* — is the foundation Norax builds on. - **[soul.md](https://soul.md)** — The concept of a configurable agent identity file originated in the OpenClaw community. Norax adopts and extends this pattern. - **The agent research community** — Work on long-horizon reliability, context engineering, behavioral state decay, and memory-augmented agents directly shaped Norax's architecture. Norax is a ground-up implementation, not a fork. It combines durable task state, target-aware verification, layered memory, and tamper-evident event chaining, while treating every model inference and external side effect as fallible. ## License Copyright 2026 Colby Caron. Licensed under the [Apache License 2.0](LICENSE).