Quickstart · The Shell · Safety · Agents · Deploy · Red-team report · Agent catalog
What this is
ONEXUS puts a capability arbiter in front of the agents it runs.
An agent declares what it needs (filesystem reach, specific outbound domains, which tools)
in a manifest, before it runs. Every call it then makes through ONEXUS is checked against
that declaration by Aegis, allowed or denied, and appended to the Chronicle ledger. An
agent that never declared network.outbound.example.com is refused when it asks ONEXUS to
reach that host, and the refusal is a recorded event rather than a silent failure.
Agents installed from the agent store run confined. Each one gets its own container that
sees none of your files, and it can reach only the hosts you approved at install, through
an egress proxy that refuses everything else. Catalog adapters that don't declare a
container still launch as ordinary processes, so for those Aegis governs the calls they
route through ONEXUS, not everything they could do on their own. The
red-team report spells out exactly
what is and isn't protected.
Trust is earned rather than assigned. Each module carries a score that moves on recorded
outcomes, and the score decides how much rope it gets — from suggest only, through
monitor, to execute, to fully autonomous. Revoking it is one click and takes effect on
the next call, not the next restart.
That is the whole idea. Everything else is the interface that makes living inside it
bearable: the workspaces, the sixteen built-in modules, the in-shell editor, the mood engine,
and the third-party agents from ONEXUS-Agents. It runs agents the way iOS runs apps: one runtime, one
manifest format, one trust model, one set of surfaces.
A workspace is a room: it owns its own agents, memory, file grants, and home tone.
You don't leave the OS to do anything. Code editor, web search, file drop, mood-driven atmosphere, agent capability sheets — all in-shell.
What v2 added
Version 2 added three groups of modules on top of the runtime:
- N1 — Perception. Sigil, a threat radar that watches Aegis trust deltas, gate verdicts, and routing traffic, broadcasts emergency Pulse alerts and can auto-activate Specter. Atlas, a temporal knowledge graph in Engram with read-time confidence decay, re-confirmation, and coexisting contradictions. A live kernel visualization in Aurora — watch Cortex route and Aegis gate in real time, with radar pings and full-surface emergency veils.
- N2 — Cognition. Prism cross-domain synthesis across workspace partitions (Aegis-gated), Chronos counterfactual reasoning over Chronicle's decision history ("what would have happened if that grant had been denied"), and Dreamweaver overnight distillation of the day's memory into a morning brief — surfaced as an Atlas graph view, a Chronos timeline, and a brief card.
- N3 — Society. Herald agent-to-agent negotiation (offer → counter → accept/reject → commit) where every commitment is Aegis-gated and the full transcript lands in Chronicle, real workspace-scoped federation sync between instances, the Serendipity anti-optimization module, and the Aurora v3 responsive layout.
A companion fix/aurora-feedback branch ships UX fixes: escape-first markdown rendering, real dispatch in-flight/error states, true token streaming, local-codebase access, and truthful capability grounding (so agents stop inventing integrations that don't exist). Design docs and plans live under docs/design/{specs,plans}/.
Quickstart
Prerequisites: Python 3.11+, Ollama (for natural-language responses — see next section), and ~6 GB free disk if you want a local LLM.
# 1. Clone ONEXUS + the agent catalog as siblings (the kernel looks for
# ../ONEXUS-Agents/ for the bundled agent catalog).
git clone https://github.com/AllStreets/ONEXUS.git
git clone https://github.com/AllStreets/ONEXUS-Agents.git
cd ONEXUS
# 2. Install the kernel + Aurora into a fresh venv.
python -m venv .venv && source .venv/bin/activate
pip install -e ".[llm,api,tui,messaging]"
# 3. Boot — single command brings up API + Aurora + WebSocket streams.
onexus serve --port 8901
Open http://127.0.0.1:8901/aurora — or just http://127.0.0.1:8901/, which redirects there — and you're in. Every new install lands you in a default Hello World workspace; create more with ⌘N, delete from the sidebar trash. First-time visitors also get a 13-page guided tour; hit ? any time to re-open it.
Serve the real backend, not a static file server. Aurora is a thin client over the FastAPI app — every panel (live provider health, the Ollama restart button, token streaming) calls /api/*. Always launch with onexus serve (uvicorn). Pointing python -m http.server at the aurora/ folder will render the shell but every /api/* call 404s, so health shows nothing and buttons do nothing.
Heads-up — without a local LLM (next section) agents only respond to pattern-matched commands (summon X, list, agents <keyword>). Plain-English questions return a keyword-search dump instead of a real recommendation. Install Ollama and the same questions get LLM-backed answers.
Local LLM (recommended — keeps you sovereign + offline)
The kernel ships with Ollama as the default inference provider. Install it once and ONEXUS picks it up automatically — no API keys, no outbound traffic, no rate limits.
# macOS
brew install --cask ollama # or grab the .dmg from ollama.com
ollama serve & # daemon on localhost:11434
ollama pull llama3.1:8b # ~5 GB · M-series default
# Smaller models that still work well:
# ollama pull llama3.2:3b # ~2 GB · 8 GB Macs
# ollama pull qwen2.5:14b # ~9 GB · better reasoning
ONEXUS auto-detects Ollama at boot — the Cortex routes natural-language questions through it, every catalog agent gets the LLM in its context, and Aegis still gates every tool call. No knobs to flip. If you quit Ollama, Settings → Providers → Restart Ollama relaunches it — on macOS it opens the Ollama menu-bar app (so it reappears in Activity Monitor and the menu bar), elsewhere it spawns a headless ollama serve — and each provider's live health (green healthy / red unavailable) is polled from /api/providers.
Cloud provider (optional override)
Two ways to add an OpenAI or Anthropic key:
In-app (recommended) — Settings → Providers → CLOUD → click + add OpenAI API key or + add Anthropic API key. Paste the key, press Enter. It's stored at ~/.local/share/nexus/provider_keys.json with chmod 0600, registered with the live kernel router immediately (no restart), re-displayed only as a tail-fingerprint like sk-…1234. Remove any time from the same row.
Environment variables — still respected, useful for CI / Docker:
export NEXUS_OPENAI_KEY=sk-...
# or
export NEXUS_ANTHROPIC_KEY=sk-ant-...
export NEXUS_DEFAULT_PROVIDER=openai # or anthropic / local / ollama
Keyboard shortcuts
⌘K workspace switcher ⌘E workshop (code + sandbox)
⌘N new workspace ⌘/ web search
⌘L cortex multi-agent launch ⌘P settings
⌘0 expanded cockpit ? open the guide
⌘⏎ send message
In the home composer you can also type cortex <prompt> — the keyword is detected and you're routed to the launcher with the rest of the message pre-filled.
Full keyboard + CLI + curl reference: docs/CHEATSHEET.md.
Footprint
| Component | Disk | RAM |
|---|
| Cloned repo (no build) | ~20 MB | — |
| Python kernel + Aurora server | — | ~100 MB |
Standalone .app (Tauri shell) | 12 MB | ~150 MB (WebView2 / WKWebView) |
| Ollama daemon | 550 MB | ~60 MB |
llama3.1:8b model loaded | 5 GB | 6–10 GB (default 8k context) |
llama3.2:3b model loaded | 2 GB | 3–4 GB |
Practical minimum: 8 GB Mac with llama3.2:3b and the cockpit-only build; comfortable: 16 GB with llama3.1:8b; headroom: 32 GB+ for larger models and big context windows.
What it does, in four pictures
The whole shell shifts color with what's happening. Aegis observes the kernel — CPU, engram activity, trust events, time of day — and the ambient mesh, the active workspace pill, the composer focus ring, the launch buttons, the capability sheet edge all recolor together.
Eight palettes total: calm focus · deep flow · routing · deliberating · creative · reflective · watchful · alert. Pick one manually from the chrome's mood pill, or let the kernel pick from observations.
The shell
Aurora is a persistent three-column workspace — sidebar, conversation, cockpit. Glass chrome. macOS-style traffic lights that actually work (red closes the tab, yellow toggles focus mode, green toggles fullscreen).
-
Workspace pills with 25 color tones to pick from on create:
-
Hover any pill → reveals a neon-red trash icon to delete that workspace
-
Recent agents block — built-in identity discs with trust tier
-
Workspace tiles show live agent counts — "agents · N" reflects distinct cortex modules you've actually chatted with in that workspace (sourced from chronicle, not just declared residents)
-
⌘L cortex launch · ⌘E workshop · ⌘/ web search · catalog · ⌘P settings
-
Persistent user footer pinned at the bottom
- Send a message and Cortex routes it: pattern + semantic + structure + workspace pin + LLM fallback
@oracle, @specter, @council mention any agent directly- Drag-and-drop files anywhere on the canvas — they're stored in workspace Engram, hashed for dedup, logged to Chronicle
- Inline permission prompts for sensitive calls: allow once · always · here · deny
- Trust feedback buttons under every agent response: thumb-up = +0.12 to that agent's trust; thumb-down = −0.22
- File diff cards when an agent proposes a refactor
- Composer pinned at the bottom regardless of thread length
- TRUST · last 60 minutes — sparkline + delta + class breakdown (routine / notable / sensitive / denied)
- Recent permissions — color-coded by class, with capability + target + status + time
- Ambient mood — mood mesh thumbnail with the kernel's current reading and contributing reasons
- Built-in agents: the count of built-in modules and runnable catalog agents, both read from the running kernel, and identity discs you can click for the full capability sheet
- Footer:
kernel.network.io = ∅ (static-verified) — the kernel itself never touches the network
Press ⌘ 0 for the expanded six-panel cockpit overlay.
⌘L (or sidebar → cortex launch, or type cortex <prompt> into the home composer) opens a multi-agent dispatcher:
- Big prompt textarea
- Every registered agent shows up as a chip — Cortex's classifier top-picks are visually marked, the primary pick gets a
PRIMARY pill so you know which one Cortex would have routed to alone
- Shortcuts:
pick top 3 for me · all available · clear
- Dispatch runs all selected agents in parallel via
asyncio.gather. Each gets its own Aegis capability check, so a denied agent fails with a clear permission_denied row instead of crashing the run.
- Every run renders as its own card with module · ok/error pill · latency · full response
- All
multi_launch_start / multi_launch_done / per-run events land in Chronicle, so the chat-history tab picks up multi-agent sessions automatically
- General — data dir, port, default provider
- Chat history — drill from workspaces → agents → individual chats with full transcripts. 50 chats per page with prev/next pagination, polls every 5s so new exchanges appear without a refresh. Each workspace's chat cards pick up that workspace's own tone gradient on the left rail.
- Security — search every Aegis-registered module; revoke any agent's trust to 0 with one click
- Providers — LOCAL section (Ollama + llama.cpp with live health dots, green for healthy / red for unavailable) and CLOUD section (
+ add OpenAI / Anthropic API key flow described above)
- Federation — peer-to-peer instance config
- Moods — current MoodEngine state + 8 atmospheres with live previews
- About — version, test count, catalog size, source link
The safety model
Aegis classifies every capability into one of four classes:
| Class | Color | Behavior |
|---|
| Routine | jewel green | always allowed, silent forever |
| Notable | calm violet-blue | auto-allow at trust ≥ 0.75, otherwise prompt |
| Sensitive | warm amber | always prompt — allow once / always here / deny |
| Privileged | coral | never auto-grant — Settings → Security only |
The kernel writes every decision to Chronicle, a SQLite ledger that ONEXUS only ever appends to. Each row is hash-chained to the one before it, so an edited or deleted row is named when the chain is verified. The Aurora cockpit log surfaces the last N entries by class. Settings → Security shows the live trust roster: search every Aegis-registered module, and click revoke to drop its trust to 0 and remove its grants.
Built-in agents
Sixteen modules ship with ONEXUS, each with its own manifest of capabilities and a trust
floor. Fourteen take messages through Cortex routing. Herald and Serendipity are called through
their own API routes, and Herald's negotiations show in the cockpit rail.
| Agent | Glyph | What it does |
|---|
| Council | two brackets weighing a bar | 3-round deliberation across the cognitive modules |
| Oracle | lens with a diamond iris | first-read analysis across whatever's in the workspace |
| Specter | crosshair in a diamond | red-team: counter-arguments and dissenting views, no flattery |
| Wraith | lines that shorten and fade | controlled forgetting: privacy hygiene, sensitive deletion |
| Legacy | cut crystal | crystallized memory: recall with citations |
| Echo | mirrored chevrons | mirror: restates the user's words to surface contradictions |
| Sentry | pulse inside a shield | watches for runaway loops, trust drops, denied calls |
| Autonomic | endless loop | autopilot: repeats approved tool chains hands-off |
| Consciousness | square turning in a square | inner state: moods, regulation, salience |
| Agents | docked tiles and an open slot | dispatches to installed third-party MCP agents |
| Sigil | radar sweep | threat radar over trust deltas, gate verdicts and routing traffic |
| Atlas | isometric cube | temporal knowledge graph with confidence that decays until re-confirmed |
| Chronos | forking timeline | counterfactuals over Chronicle: what if that grant had been denied |
| Prism | prism splitting a beam | synthesis across workspaces, gated by Aegis |
| Herald | pennant on a staff | agent-to-agent negotiation where every commitment is gated |
| Serendipity | two sparks | surfaces the novel, low-relevance facts optimization would hide |
Click any disc in the cockpit to see its declared tools, permission classes, trust floor, and network reach.
Architecture
The kernel never touches the network. Every outbound HTTP request from any built-in module goes through aegis.network() which logs to Chronicle, checks the agent's net.* capability declaration, and runs through AegisTransport (a wrapped httpx client). A static invariant test enforces that no kernel module other than aegis.py imports httpx or requests.
In-OS tools
You don't leave the OS to write code, search the web, or store files.
Workshop · code + sandbox
Open with ⌘E. Pick a runtime (Python · JavaScript · shell). Hit Run (⌘⏎). Code executes in a subprocess sandbox: stripped env (ONEXUS_SANDBOX=1), 8-second timeout, captured stdout/stderr (max 32 KB per stream), exit code + elapsed time, logged to Chronicle. History popover keeps the last 30 runs — click to reload, clear to wipe.
Web search
Open with ⌘/. Routes through aegis.network() to DuckDuckGo's instant-answer API by default (no tracking). Configure NEXUS_BRAVE_KEY to use Brave Search for organic results. Wikipedia is always a fallback so you never see an empty page. History popover with last 50 queries.
File drop
Drag any file anywhere on the conversation canvas — the surface gets a mood-tinted "Drop files into this workspace" overlay. Files are stored under <workspace_root>/.onexus/uploads/, hashed for dedup, registered with Engram episodic memory, logged to Chronicle.
Catalog
ONEXUS ships with the AllStreets/ONEXUS-Agents catalog bundled — every entry is a single JSON manifest under catalog/<category>/<slug>.json, spanning 40 categories. Entries marked runnable are derived from each repo's own declared metadata, not from anything executed here, so treat them as leads; 21 carry hand-maintained adapters. Browse from the sidebar's agent catalog link, filter by category / runnable-only / search, click Launch on any runnable card. Whatever you launch is still gated by Aegis like everything else.
Agent store
The store is the part of the catalog that can be installed by a program: 53 agents whose
recipe was read from their own published package, then built, started confined and asked
for their tools before they were listed. Installing one pulls or builds its image, starts it
in a container with none of your files, and asks it for its tools over MCP; nothing is saved
unless all three steps pass. You pick which of the hosts found in its code it may reach, and
the egress proxy refuses the rest. Open it from the sidebar's agent store link.
The catalog rebuilds nightly via a GitHub Actions cron that reads the catalog repo's head SHA and pushes a fresh Docker image to GHCR.
Deploy
Local
onexus serve --port 8901
Open http://127.0.0.1:8901/aurora. Data lives in ~/.local/share/nexus/.
Standalone .app (Tauri wrapper)
ONEXUS ships with a native desktop shell — a 12 MB Tauri binary that hosts the Aurora UI in a host WebView and spawns the Python kernel as a child process. Real macOS traffic lights, native menu bar, Finder drag-and-drop, file watcher that auto-reloads when you edit nexus/ source.
brew install rust # one-time, if you don't have it
cargo install tauri-cli --version "^2" # one-time
cd standalone
cargo tauri build # → target/release/bundle/macos/ONEXUS.app
cp -R target/release/bundle/macos/ONEXUS.app /Applications/
open /Applications/ONEXUS.app
What the .app does on launch:
- Walks port candidates
8901, 8902, …, 8909 and probes /api/system/status
- If one is already an ONEXUS server, attaches to it; otherwise picks the first free port
- Refuses to glue itself to a non-ONEXUS service on the port (so SMADP / jupyter / random dev servers can't hijack the WebView)
- Spawns
.venv/bin/onexus serve --port <resolved> from your project root
- Opens a native WebView at
http://127.0.0.1:<resolved>/aurora
- Kills the spawned server on quit
Built-in menu (no terminal needed for the edit loop):
| Menu | Shortcut | Action |
|---|
| File → Reload Backend | ⌘⇧R | kill + respawn the Python server, then reload the WebView (use after editing nexus/*.py) |
| View → Reload Aurora | ⌘R | reload just the WebView (use after editing nexus/aurora/*.{html,css,js}) |
| File → Quit | ⌘Q | kill the server and quit |
The .app also runs a file watcher: save any .py under nexus/ and the backend reloads automatically; save anything under nexus/aurora/ and the WebView refreshes. No ⌘R needed for the common edit / save / test loop. Full notes: standalone/README.md.
Docker
docker build -t onexus:local .
docker run -p 8000:8000 -v $(pwd)/.data:/data onexus:local
Railway (one-click)
A railway.json is included. From the Railway dashboard:
- New Project → Deploy from GitHub repo → AllStreets/ONEXUS
- Railway reads
railway.json and builds with the Dockerfile
- Add a volume mounted at
/data for persistent workspace storage
- Health probe is automatic via
/api/system/health
Full guide: docs/DEPLOY.md.
What's verified
Adversarially reviewed. docs/REDTEAM-AEGIS.md is a three-round
red-team of Aegis by its own author. Round 1 attacked the arbiter: revoking an agent
didn't stop it, because the arbiter reads grants before trust. Round 2 attacked the
boundary: launched agents could read the operator's secrets, and the ledger could be
edited without detection. Round 3 attacked what an agent does on its own: it could read
your files, open its own sockets and write anywhere, so an adapter can now run in a
locked-down container behind an egress proxy. Every finding was committed before its
fix. One finding is left open on purpose, and the report says what is still not
protected, including that only two catalog adapters run confined so far.
.venv/bin/python -m pytest tests/redteam/ -q
Safety and correctness properties, and the test that checks each one. "Static" means the
test reads source code; it is not enforced while the program runs.
| Property | How it's checked |
|---|
| A revoked agent loses its grants, whoever lowered its trust | tests/redteam/test_aegis_redteam.py |
| A launched agent sees only the environment variables and provider keys it declares | tests/redteam/test_aegis_redteam_round2.py (real child processes) |
| An edited or deleted Chronicle row is named on verification | tests/redteam/test_aegis_redteam_round2.py |
| A confined agent sees none of the operator's files and reaches only its declared hosts, through a proxy that refuses the rest | tests/redteam/test_aegis_redteam_round3.py (real containers; needs Docker) |
| Agent launch commands are allowlisted | tests/agents/test_launcher_allowlist.py |
| Optional API token gate covers HTTP and WebSocket | tests/api_safety/test_api_token.py |
| Permission inbox requests round-trip to a decision | tests/api_safety/test_permissions_routes.py |
| No kernel module except Aegis imports an HTTP client | static scan of each module's source in tests/release/test_v1_acceptance.py |
Interface behaviour (the mood engine, live cockpit panels, close buttons on every overlay)
is covered under tests/aurora/. Style rules for Aurora live in the contributing notes below.
Contribute
The catalog is the right place to add an agent — open an issue at ONEXUS-Agents with the agent's repo URL and a one-liner. The nightly pipeline does the rest.
I built ONEXUS with coding agents. I set the direction and the constraints, and I review, test and decide what stays; the red-team above is the clearest example of that split. The design records, one decision and its reasons per file, are in docs/design.
For kernel and Aurora work, the spec is the source of truth. Plans live under docs/design/plans/. Aurora's style rules, such as no emoji in any served asset, are checked by tests under tests/aurora/.
License
Apache-2.0. Copyright 2026 Connor Evans.
The ONEXUS kernel, Aurora dashboard, modules, agents, and standalone Tauri shell in this repository are released under the Apache License 2.0 — free for commercial and non-commercial use, including the patent grant. Each bundled catalog agent retains its own upstream license; see the license field on every entry in ONEXUS-Agents.
Full text at LICENSE.
ONEXUS — an operating system for agents.
github.com/AllStreets/ONEXUS · parent catalog · issues
