Omnius

Omnius is a local-first agentic coding runtime: terminal UI, autonomous coding loop, REST daemon, model router, memory layer, media tools, Telegram bridge, and peer-to-peer inference mesh in one CLI.

It is designed for open-weight and user-controlled models first, while still routing cleanly through Ollama, vLLM, OpenAI-compatible endpoints, OpenRouter, Groq, Chutes, sponsor peers, COHERE peers, and other configured providers.

Install

npm install -g omnius
omnius

Requirements:

• Node.js 22 or newer
• npm 10 or newer for published CLI use
• pnpm 9 or newer for workspace development
• A local model or configured remote endpoint

Start the REST daemon:

omnius serve

The daemon defaults to http://127.0.0.1:11435. Open the interactive API docs at http://127.0.0.1:11435/docs.

Register the native system tray indicator (Linux, macOS, and Windows x64):

omnius tray install
omnius tray status

The per-login indicator observes the daemon over loopback, checks health and npm updates every 10 seconds, and provides dashboard, logs, and explicit daemon controls. Its version row is passive when current and becomes a verified global update action only when a newer exact semver is available. See the system tray guide, including Ubuntu/GNOME setup.

Agent Discovery

The npm package ships its complete documentation and a machine-readable capability catalog. An agent does not need to inspect Omnius source or guess which endpoint owns a capability:

omnius discover "bring your own inference"
omnius show workflow.choose-entrypoint
omnius show layer.orchestration
omnius show store.project
omnius show provider.anthropic
omnius show provider.gemini
omnius show tool.web-search
omnius discover "evidence-bound decision impasse"
omnius show tool.adjudicate
omnius discover "osint research"
omnius show capability.osint-research
omnius capabilities --json

With the daemon running, begin at GET /v1/discovery/bootstrap. The same discovery cascade is available at GET /v1/discovery, with exact entry expansion at GET /v1/discovery/{id}. The live API contract remains available at /openapi.json, direct tool metadata at /v1/tools, and skills at /v1/skills.

Start with the discovery guide when integrating another agent or service, and use the agent system map to trace layers, modules, runtimes, and state ownership. Use bring-your-own inference for provider protocols and keys, and tools and web search for the distinction between direct tools and agent-bound tools. The evidence-bound adjudication guide explains how a top-level full agent freezes an admissible record, isolates a genuine decision impasse from accumulated working context, fans review out across fresh evidence-scoped constituents, validates evidence citations and quorum, and produces a durable verdict receipt. Top-level runtimes execute constituents in a dedicated full_sub_agent process profile that cannot load tools, project context, memory, or the ambient parent environment. The process runs outside the project directory. Cancellation and deadlines terminate its child processes; ordinary child transport failure is recorded before bounded direct fallback. Planner schema drift uses a deterministic question-framing fallback, and durable artifact replay verifies the case, findings, verdict, and receipt hashes without new inference. The categorized OSINT research guide documents the local discover → exact expansion → explicit web-tool workflow.

What Omnius Does

• Runs autonomous coding tasks, edits files, executes tools, tests changes, and iterates on failures.
• Resolves genuine decision impasses in fresh evidence-scoped contexts that reduce parent-context anchoring, with host-validated citations, quorum, preserved dissent, and durable verdict receipts.
• Provides a dense terminal UI for model selection, endpoint routing, task control, shell output, voice, sponsors, Telegram, and system telemetry.
• Exposes a REST daemon with OpenAI/Ollama-compatible inference, agentic task execution, memory, skills, tools, MCP, events, voice, projects, and governance endpoints.
• Routes models through local, cloud, sponsor, and peer-to-peer endpoints without assuming local Ollama is the only source.
• Supports realtime spoken conversation for ASR/TTS clients through /realtime and REST realtime: true.
• Supports image, video, sound, music, TTS, ASR, voice clone references, Telegram media workflows, and sponsor-provided media generation.
• Keeps project runtime state in .omnius/, which is intentionally ignored by git.

Common Workflows

omnius "inspect this repo and summarize the main entrypoints"
omnius serve

/help                 command help
/model                select or inspect the active model
/endpoint             select or configure local, cloud, sponsor, or peer endpoints
/title                name the current session
/realtime             toggle short ASR/TTS-oriented conversation mode
/voice                choose TTS, voice-clone, voicechat, and ASR controls
/voice asr            select, set up, activate, or test an exact ASR engine/model
/indicator            reconcile the daemon, then start the native tray indicator
/update check         force an update availability check
/update quick         run the verified global update with live TUI progress
/update full          run the full clean/build/install/restart verification flow
/broker               inspect model broker, RAM/VRAM thresholds, and loaded models
/sponsor              expose local or upstream capacity to peers
/cohere               participate in distributed COHERE inference
/telegram             configure or toggle the Telegram bridge
/skills               list explorable skills and docs memories
/pause                pause after the current turn boundary
/stop                 interrupt the active run
/resume               resume saved state

Current Feature Areas

| Area | What to read | | --- | --- | | Install and setup | Install, First run, Model providers | | Agent discovery | Discovery cascade, machine catalog, agent integration | | Bring your own inference | Provider protocols and keys | | Tools and web search | Tool discovery and invocation | | Evidence-bound adjudication | Adjudication tool, panel workflow, verdict contract, and harness | | Terminal workflows | TUI workflows, Slash commands | | Web dashboard | All dashboard routes, workspaces, sessions, Voice, Generate, updates, and observability | | REST daemon | REST reference, REST quickref, OpenAPI source | | System tray | Cross-platform tray and Ubuntu setup | | Realtime voice chat | Realtime guide | | TTS and selectable ASR | Voice/vision REST guide, Dashboard Voice page | | Sponsor and COHERE mesh | Sponsor and COHERE guide | | Telegram bridge | Telegram guide | | Media generation | Media guide | | Operations | Runtime hygiene, Security and remote access | | Service compatibility | Runtime version gate | | Architecture | Architecture overview | | Agent-explorable docs | Agent memory docs index |

Web Dashboard

omnius serve exposes a self-contained operational dashboard at http://127.0.0.1:11435/. All pages use the same compact NOCLIP-derived style tokens and responsive observability-card grid, while keeping workspace, model, session, run, service, and update state visible instead of hiding it behind decorative pages.

| Route | Purpose | | --- | --- | | /chat (/) | Stateful browser and imported TUI chats, full-history hydration, live run recovery, attachments, files, plan/context, and steering check-ins | | /agent | One-shot task contracts, personas/profiles, tool/isolation controls, run records, output, and events | | /voice | Voicechat, exact TTS model/options, clone references, ASR engine/model setup and activation, real-file ASR testing, transcript, and TTS testing | | /generate | Image/video/audio/music jobs, AV analysis, model/store controls, relocation progress, and global gallery | | /projects | Scan, register, rename, activate, and remove workspaces | | /dashboard (/jobs) | CPU/RAM/GPU/VRAM, processes, scheduler, services, usage, and verified updates | | /activity | Live run/tool/memory/engine event observability | | /discover | Agent bootstrap, capability intent search, and exact entry expansion | | /settings (/config) | Models, endpoints, voice, runtime, access, keys, appearance, and services |

The clickable sidebar brand opens the registered-workspace picker. Workspace selection scopes preferences, files, session history, chat pins/folders/search, and agent defaults. Chats, TUI visual history, and one-shot agent runs are distinct records: /quit, /exit, manual-save noise, empty histories, and duplicate TUI transcripts are rejected from the chat projection; selecting a valid session loads its full history and in-flight status from the daemon. The chat top bar also reports the effective API base path and authentication mode. Streams retain split frames, Stop terminates the daemon-owned process lease, and assistant-provided web/file links stay inert until the daemon returns a validation receipt.

The dashboard checks for updates every 10 seconds. An update button appears only for a newer exact semver and drives POST /v1/update, then polls the durable transaction until the global npm package, resolved executable, restarted daemon, package/boot hashes, and tray runtime are reconciled. See the complete dashboard guide for state ownership, security, page-by-page behavior, and exact REST flows.

Terminal Over SSH

The TUI paints for a local terminal, where a full-area repaint costs nothing. Over a network the same cadence has to share the link with your keystrokes, so Omnius detects a remote session (SSH_TTY / SSH_CONNECTION / SSH_CLIENT) and paces itself: decorative chrome animates slower, a wheel-scroll burst is collapsed into a single repaint, unchanged footer frames are not re-sent, and the mouse filter allows more time for escape sequences split across packets. Nothing changes about how the TUI looks, and local sessions are unaffected.

Detection is environment-based, so it can miss a session where those variables do not reach the process — most often tmux or mosh, whose panes may inherit a stale environment from the server. Force the profile when that happens:

OMNIUS_TUI_PACING=remote omnius   # pace for a network link
OMNIUS_TUI_PACING=local omnius    # force local cadence

If scrolling or typing still feels heavy, OMNIUS_TUI_PROFILE=compatible additionally drops the animated truecolor chrome, and OMNIUS_TUI_PERF=1 logs any content reflow that overruns its frame budget to stderr.

Shared Media Dependencies

Image, video, audio, and music generation share a single, system-wide dependency store instead of duplicating heavy runtimes per project or per Telegram group.

Earlier builds wrote a private Python venv plus Hugging Face / Torch / pip caches under every scoped working directory (for example …/telegram-creative/<group-id>/.omnius/image-gen/.venv). On a busy machine the same multi-gigabyte diffusers stack and model weights were re-downloaded once per group — tens of gigabytes of pure duplication.

Everything now resolves to one source of truth under ~/.omnius (override with OMNIUS_HOME):

| Location | Holds | | --- | --- | | ~/.omnius/runtimes/<kind>/.venv-<backend> | One shared Python venv per kind+backend (image/video/audio) | | ~/.omnius/models/huggingface/{hub,transformers,diffusers} | Shared model weights — downloaded once, reused everywhere | | ~/.omnius/models/{torch,cache,pip-cache} | Shared Torch hub, XDG, and pip caches | | ~/.omnius/models/_meta.json | LRU usage index for automatic disk-pressure eviction | | ~/.omnius/media/{images,videos,audio,music} | Global generated-media gallery (project-independent) |

Project directories keep only lightweight session artifacts; no venvs or model weights are written per project.

Migrate and dedup existing machines. A one-time cleanup consolidates any legacy per-group caches into the unified store — unique weights are moved (never re-downloaded), duplicates and stale venvs are reclaimed:

# TUI — current project only
/models cleanup
# TUI — every project + nested scoped group on this machine (dry-run first)
/models cleanup --all --dry-run
/models cleanup --all

# REST — preview, then apply
curl -s -X POST localhost:11435/v1/media/migrate -H 'content-type: application/json' -d '{"dryRun":true}'
curl -s -X POST localhost:11435/v1/media/migrate -H 'content-type: application/json' -d '{}'
# Inspect store + reclaimable legacy caches
curl -s localhost:11435/v1/media/store

Generate over REST. The daemon (default 127.0.0.1:11435, a port in the IANA dynamic/private range that avoids common system-service collisions) exposes the local generators so any user on the machine can list models, generate, and browse the global gallery without the CLI:

curl -s localhost:11435/v1/media/models
curl -s -X POST localhost:11435/v1/media/image -H 'content-type: application/json' -d '{"prompt":"a compact robot painter"}'
curl -s -X POST localhost:11435/v1/media/music -H 'content-type: application/json' -d '{"prompt":"warm lo-fi piano loop"}'
curl -s localhost:11435/v1/media/gallery

The same surface drives the Generate tab in the web UI (http://127.0.0.1:11435) — pick a kind (image/video/audio/music), choose a model loaded from the system, generate, and review every previously generated file in one global gallery.

Recent Highlights

• The dashboard now has nine route-level operational surfaces with shared modular observability grids, a searchable workspace picker, and project-scoped navigation state.
• Chat history unifies persisted browser sessions with quality-filtered TUI transcripts, rejects command/noise sessions such as /quit, hydrates full history on selection, and exposes summaries, follow-up suggestions, reactive live deltas, and canonical deletion.
• /indicator reconciles daemon ownership and health before launching the tray; the tray polls every 10 seconds and turns its version row into a retryable verified-update action only when an update exists.
• Dashboard, tray, and TUI update actions now share an exact-version global transaction with live phase/output and package, executable, daemon, hash, restart, and tray verification.
• TTS exposes GLaDOS, Overwatch, luxtts:announcer-testchamber03, and configurable Voicebox models; ASR independently exposes Whisper, managed transcribe-cli, Nemotron readiness, and pinned Microsoft VibeVoice ASR with Jetson/ARM64 CUDA-aware setup.
• LuxTTS auto-setup on Jetson ARM64 requires CPU ONNX Runtime at import time, validates CUDA Torch separately against the host runtime, preserves existing caches during repair, and never substitutes generic PyPI Torch or automatic sudo for an AGX Orin deployment.
• /realtime and REST realtime: true provide short, natural, SOUL.md-aware conversation for ASR/TTS clients.
• Endpoint setup and sponsor setup aggregate models from all enabled endpoints, including external OpenAI-compatible routers.
• /sponsor can expose text inference and media generation for image, video, sound, and music with per-modality limits.
• Sponsor and COHERE status surfaces now use shared telemetry concepts: concurrency, request rate, daily tokens, peer usage, model usage, and remote system metrics.
• The TUI reports token production rate as t/s, supports Shift+Enter multiline input, and renders dynamic shell output inside bounded Unicode cards.
• Telegram state is scoped by user and group, supports durable reply preferences, and feeds raw platform/tool failures back into the agent loop.
• Telegram media ingress is byte- and duration-bounded, cache-only before routing, deduplicated by Telegram file identity, and evidence-gated after admission. Speech uses scoped transcription; music/general audio uses typed semantic or explicitly acoustic-only analysis without false listening claims.
• Telegram public creative work now includes typed PDF/DOCX creation and hash-guarded review, fixed-operation FFmpeg audio editing, and root-confined image crop/resize/mask/composite workflows. Host-signed content capabilities bind review evidence and durable Telegram delivery to the exact artifact bytes.
• Ollama pool cleanup now accounts for process groups and orphan runner processes that can keep VRAM pinned.
• REST documentation is available both as human docs and as Omnius-discoverable docs skills.

REST API

Start the daemon (default http://127.0.0.1:11435; interactive docs at /docs, machine spec at /openapi.json):

omnius serve

For shared deployments, gate access with scoped bearer keys (read < run < admin):

OMNIUS_REST_API_KEYS="read-key:read:grafana,run-key:run:ci:60:100000:3,admin-key:admin:ops" omnius serve
# then: Authorization: Bearer <key>

The complete supported endpoint inventory follows. The canonical machine contract is generated from packages/cli/src/api/openapi.ts, validated against docs/reference/rest-api.md, and projected into the generated block below. pnpm docs:check now fails when any of those three surfaces drift. Browser HTML pages, Swagger static assets, and implementation-only compatibility bridges are intentionally outside this stable REST contract.

Docs And Compatibility Aliases

| Method | Path | Purpose | | --- | --- | --- | | GET | /docs | Swagger UI | | GET | /api/docs | Swagger UI alias | | GET | /openapi.json | OpenAPI JSON | | GET | /openapi.yaml | OpenAPI YAML | | GET | /v3/api-docs | OpenAPI alias | | GET | /swagger.json | Swagger-era alias | | GET | /api-docs | OpenAPI alias | | GET | /swagger-ui | Swagger UI alias | | GET | /redoc | ReDoc renderer | | GET | / | HATEOAS API root when the client does not request HTML | | GET | /help | Compact daemon integration help | | GET | /v1/routes | Flat grep-friendly daemon route summary | | GET | /routes | Route-summary compatibility alias | | GET | /asyncapi.json | AsyncAPI 2.6 voicechat WebSocket contract | | GET | /asyncapi | AsyncAPI compatibility alias |

Health And Observability

| Method | Path | Purpose | | --- | --- | --- | | GET | /health | Liveness probe | | GET | /health/ready | Backend readiness | | GET | /health/startup | Startup probe | | GET | /version | Package version and platform | | GET | /metrics | Prometheus metrics | | GET | /v1/events | Server-sent event stream | | GET | /v1/usage | Token usage and rate limits | | GET | /v1/audit | Audit log query | | GET | /v1/cost | Cost tracker | | GET | /v1/system | CPU, RAM, GPU, and system snapshot |

Discovery

| Method | Path | Purpose | | --- | --- | --- | | GET | /v1/discovery/bootstrap | Compact agent bootstrap and start-here map | | GET | /v1/discovery | Search layers, workflows, runtimes, modules, stores, and capabilities | | GET | /v1/discovery/{id} | Expand one stable capability entry |

Inference And Chat

| Method | Path | Purpose | | --- | --- | --- | | GET | /v1/models | Aggregated model list | | POST | /v1/chat/completions | OpenAI-compatible chat completion | | POST | /v1/chat | Stateful Omnius chat | | POST | /api/chat | Ollama-compatible chat alias | | POST | /v1/generate | Ollama-compatible one-shot generation | | POST | /api/generate | Ollama-compatible generate alias | | POST | /v1/embeddings | OpenAI-compatible embeddings | | POST | /api/embed | Ollama-compatible embeddings alias | | GET | /api/tags | Ollama-compatible model tags | | POST | /realtime | Text-only voice-adapter reply from a transcript | | POST | /v1/realtime | Auth-scoped realtime adapter alias | | GET | /v1/chat/sessions | Workspace-scoped persisted browser chats and importable TUI sessions | | GET | /v1/chat/sessions/{id} | Hydrate full session history, transcript, and in-flight state | | DELETE | /v1/chat/sessions/{id} | Permanently delete a canonical chat or TUI history session | | POST | /v1/chat/sessions/{id}/summarize | Generate + cache an inference-based session title/summary | | POST | /v1/chat/suggest-followup | Suggest one short next-message follow-up (ghost-text input) | | GET | /v1/chat/sessions/{id}/status | Reactive recall: live run status + unseen deltas (?since=<seq>) | | POST | /v1/chat/sessions/{id}/pause | Pause the exact daemon-owned chat generation at a safe admission boundary | | POST | /v1/chat/sessions/{id}/resume | Resume the exact paused daemon-owned chat generation | | POST | /v1/chat/sessions/{id}/stop | Stop the daemon-owned chat process lease; idle/terminal calls are idempotent | | POST | /v1/chat/check-in | Steering check-in for active chat | | POST | /v1/chat/attachments | Upload an attachment for a stateful chat | | POST | /v1/links/validate | Validate an external HTTP(S) destination under the daemon egress policy |

Session History Contract

GET /v1/chat/sessions is a history index, not merely a list of processes that are currently active. It returns canonical persisted browser chats for the selected workspace and, by default, quality-filtered TUI visual sessions that can be imported on demand. Pass ?root=/absolute/workspace to scope the list and ?include_tui=0 to omit TUI history. Exit-only inputs such as /quit and /exit, manual-save noise, empty transcripts, and duplicate normalized TUI sessions are rejected by the session-quality projection rather than presented as chats.

Selecting a row should call GET /v1/chat/sessions/{id}. That response hydrates the complete public message history (system prompts are intentionally omitted), the original TUI transcript when applicable, token counts, timestamps, source and project identity, and any in-flight run with a bounded partial-output tail. Use the status endpoint with ?since=<seq> for cheap reactive polling while a run is active. DELETE /v1/chat/sessions/{id} is an admin operation and removes the canonical record; deleting only a browser-side row does not remove daemon history.

Pause and resume use the exact session and active external-run identity. Both operations require run scope. An idle session returns 200. An accepted request returns 200 with the lifecycle acknowledgement, owner generation, current phase, resumability, and pending acknowledgement count. A lifecycle rejection returns 409. A live owner that does not acknowledge within the control deadline returns 504. Clients must not treat a local UI pause as a daemon pause.

POST /realtime and /v1/realtime are text-only conversation adapters. They accept transcript text through message, text, recent_turn, asr_text, or callerText, optionally accept adapter-local soul_md, and can return plain text with Accept: text/plain or format: "text". ASR and TTS remain separate operations.

Agentic Runs

| Method | Path | Purpose | | --- | --- | --- | | POST | /v1/run | Submit agentic task | | GET | /v1/runs | List runs | | GET | /v1/runs/{id} | Get run details | | GET | /v1/runs/{id}/output | Read captured run output and status | | DELETE | /v1/runs/{id} | Abort run | | POST | /v1/todos | Create or update todos for current session | | GET | /v1/todos | List sessions with todos | | GET | /v1/todos/{session_id} | Get session todos | | DELETE | /v1/todos/{session_id} | Delete session todos | | POST | /v1/evaluate | Evaluate a run | | POST | /v1/index | Trigger repository indexing |

Configuration, Keys, Profiles, Projects

| Method | Path | Purpose | | --- | --- | --- | | GET | /v1/config | Read daemon config | | PATCH | /v1/config | Update daemon config | | GET | /v1/config/model | Current model | | PUT | /v1/config/model | Switch model | | POST | /v1/config/model/check | Probe model readiness with non-empty text | | GET | /v1/config/endpoint | Current endpoint | | PUT | /v1/config/endpoint | Switch endpoint | | POST | /v1/config/endpoint/test | Probe endpoint | | GET | /v1/config/endpoint/history | Endpoint history | | DELETE | /v1/config/endpoint/history | Remove endpoint history item | | POST | /v1/share/generate | Generate remote-access share URL | | GET | /v1/keys | List runtime API keys | | POST | /v1/keys | Mint runtime API key | | DELETE | /v1/keys/{prefix} | Revoke runtime API keys by prefix | | GET | /v1/profiles | List tool profiles | | POST | /v1/profiles | Create tool profile | | GET | /v1/profiles/{name} | Get profile | | DELETE | /v1/profiles/{name} | Delete profile | | GET | /v1/projects | List known projects | | DELETE | /v1/projects | Unregister a project | | GET | /v1/projects/current | Current project | | POST | /v1/projects/switch | Switch project | | POST | /v1/projects/register | Register project | | POST | /v1/projects/rename | Rename project | | GET | /v1/projects/preferences | Read project preferences | | PUT | /v1/projects/preferences | Patch project preferences | | DELETE | /v1/projects/preferences | Reset project preferences | | GET | /v1/projects/scan | Scan configured roots for discoverable workspaces | | GET | /v1/admin/access | Read the daemon network access mode | | POST | /v1/admin/access | Change and persist access mode from loopback only |

Skills, Commands, Tools, MCP

| Method | Path | Purpose | | --- | --- | --- | | GET | /v1/skills | List skills | | GET | /v1/skills/{name} | Load skill content | | GET | /v1/commands | List slash commands | | POST | /v1/commands/{cmd} | Execute slash command | | GET | /v1/tools | List tools (built-in + external) | | POST | /v1/tools/register | Register an application-specific external tool | | GET | /v1/tools/{name} | Tool metadata | | DELETE | /v1/tools/{name} | Unregister an external tool | | POST | /v1/tools/{name}/call | Call tool | | POST | /v1/tools/{name}/eval | Evaluate an external tool against test cases | | GET | /v1/mcps | List MCP servers | | GET | /v1/mcps/{name} | MCP server details | | POST | /v1/mcps/{name}/call | Call MCP tool | | GET | /v1/hooks | Hook registry | | GET | /v1/agents | Agent type registry | | GET | /v1/codegraph/snapshot | Code graph snapshot | | GET | /v1/codegraph/events | Code graph SSE |

Registering Application-Specific Tools

Applications can register their own tools so Omnius agents can discover and invoke them alongside built-ins. transport.type selects the bridge:

• http makes Omnius POST {name, args, session_id} to the application's callback_url and relay the result.
• mcp proxies to a named tool on an MCP server and can auto-connect from the supplied connection descriptor.

Registrations persist per workspace at .omnius/external-tools.json, appear in GET /v1/tools, and use the same scope and off-device security gates as built-in tools. Registration needs run scope; a non-loopback caller needs admin.

curl -s -X POST localhost:11435/v1/tools/register -H 'content-type: application/json' -d '{
  "name": "lookup_order",
  "description": "Look up an order by id",
  "parameters": {"type":"object","properties":{"id":{"type":"string"}},"required":["id"]},
  "security": {"requires_scope":"run","risk":"low"},
  "transport": {"type":"http","callback_url":"https://app.internal/tools/lookup_order","auth_header":"Bearer …"}
}'
curl -s localhost:11435/v1/tools/lookup_order
curl -s -X POST localhost:11435/v1/tools/lookup_order/call -H 'content-type: application/json' -d '{"args":{"id":"A-1001"}}'
curl -s -X POST localhost:11435/v1/tools/lookup_order/eval -H 'content-type: application/json' -d '{"cases":[{"name":"known","args":{"id":"A-1001"},"expect":{"success":true}}]}'
curl -s -X DELETE localhost:11435/v1/tools/lookup_order

The MCP equivalent uses a transport such as {"type":"mcp","server":"acme","tool":"search","connect":{"url":"https://app.internal/mcp","transport":"streamable-http"}}.

AIWG

| Method | Path | Purpose | | --- | --- | --- | | GET | /v1/aiwg | AIWG root and control map | | GET | /v1/aiwg/frameworks | List frameworks | | GET | /v1/aiwg/frameworks/{name} | Framework details | | GET | /v1/aiwg/frameworks/{name}/content | Tier-aware content | | GET | /v1/aiwg/skills | List AIWG skills | | GET | /v1/aiwg/skills/{name} | Load AIWG skill | | GET | /v1/aiwg/agents | List AIWG agents | | GET | /v1/aiwg/agents/{name} | Load AIWG agent | | GET | /v1/aiwg/addons | List AIWG addons | | POST | /v1/aiwg/use | Tier-sized activation bundle | | POST | /v1/aiwg/expand | Expand matching AIWG item |

Memory, Sessions, Context

| Method | Path | Purpose | | --- | --- | --- | | GET | /v1/memory | Memory backend summary | | POST | /v1/memory/search | Search memory | | POST | /v1/memory/write | Write memory | | GET | /v1/memory/episodes | List episodes | | GET | /v1/memory/failures | List failure records | | POST | /v1/memory/ingest | Ingest content or files into memory | | GET | /v1/memory/entities | List extracted memory entities | | POST | /v1/memory/jobs/run | Run a named memory-maintenance job | | POST | /v1/memory/feedback | Record relevance or quality feedback for a memory item | | POST | /v1/memory/speaker-identities/enroll | Admin-only, explicit-consent speaker exemplar enrollment in one exact vector space | | POST | /v1/memory/speaker-identities/match | Admin-only provisional speaker candidate matching without durable assignment | | GET | /v1/sessions | List task sessions | | GET | /v1/sessions/{id} | Get session history | | GET | /v1/context | Current context snapshot | | GET | /v1/context/window-dumps | List persisted outbound model context-window dumps | | GET | /v1/context/window-dumps/{id} | Fetch a full outbound model context-window dump | | POST | /v1/context/save | Save context entry | | GET | /v1/context/restore | Build restore prompt | | POST | /v1/context/compact | Request compaction |

Context-window dumps are written before backend inference for main agents, sub-agents, internal runners, and adversary audits. Query GET /v1/context/window-dumps?agent_type=main for summaries with signal/noise metrics, or fetch a full payload by id. Dumps include focus-supervisor state when a next-action contract is active. Set OMNIUS_CONTEXT_WINDOW_DUMP_DIR to move the store, OMNIUS_DISABLE_CONTEXT_WINDOW_DUMPS=1 to disable it, and OMNIUS_FOCUS_SUPERVISOR=off|auto|strict to tune focus enforcement.

Files, Web, Nexus, Ollama Pool

| Method | Path | Purpose | | --- | --- | --- | | GET | /v1/files | List workspace directory | | POST | /v1/files/read | Read workspace file | | GET | /v1/files/raw | Stream raw workspace bytes with content type and range support | | HEAD | /v1/files/raw | Inspect raw-file response metadata | | GET | /v1/web/search | Inspect web-search availability, schema, and security policy | | POST | /v1/web/search | Search the web directly through the Omnius tool runtime | | GET | /v1/web/fetch | Inspect web-fetch availability, schema, and security policy | | POST | /v1/web/fetch | Fetch a URL directly through the Omnius tool runtime | | GET | /v1/web/crawl | Inspect web-crawl availability, schema, and security policy | | POST | /v1/web/crawl | Crawl a website directly through the Omnius tool runtime | | GET | /v1/nexus/status | Nexus peer state | | GET | /v1/sponsors | Sponsor directory cache | | GET | /v1/ollama/pool/processes | Ollama process inventory | | POST | /v1/ollama/pool/cleanup | Cleanup stale Ollama pool processes |

The /v1/web/* routes are stable aliases of the shared tool registry. GET returns the corresponding tool metadata. POST uses the same authentication, profile, origin, timeout, output-size, audit, and network-egress policy as a direct tool call. Send search requests as {"args":{"query":"...","num_results":5,"provider":"duckduckgo"}} and fetch requests as {"args":{"url":"https://example.com"}}. Crawl uses the schema returned by its GET route and requires the browser dependencies that the metadata reports. POST responses use the standard ToolResult envelope.

Voice, Audio, Vision

| Method | Path | Purpose | | --- | --- | --- | | GET | /v1/voice/state | Voice runtime status | | POST | /v1/voice/start | Select an optional model, enable voice, and wait for readiness | | POST | /v1/voice/stop | Pause daemon voice input while leaving TTS warm | | GET | /v1/voice/models | TTS models | | POST | /v1/voice/models/switch | Switch and enable an exact TTS model by default | | POST | /v1/voice/models/{modelId}/pull | Install runtime prerequisites and pull one managed TTS model | | POST | /v1/voice/models/{modelId}/deploy | Pull and deploy one managed CUDA TTS model | | GET | /v1/voice/supertonic-settings | Voice tuning settings | | POST | /v1/voice/supertonic-settings | Update voice tuning settings | | GET | /v1/asr/engines | Canonical ASR engines/models, capabilities, readiness, and selection | | GET | /v1/asr/status · /v1/asr/selection | Selected engine/model and runtime status | | GET | /v1/asr/downloads | List persistent ASR weight download and deployment transitions | | POST | /v1/asr/downloads | Start or resume an ASR weight download | | GET | /v1/asr/downloads/{engineId}/{modelId} | Poll one ASR download and deployment transition | | POST | /v1/asr/downloads/{engineId}/{modelId} | Start or resume this model download | | POST | /v1/asr/downloads/{engineId}/{modelId}/retry | Retry or resume a failed or interrupted ASR weight download | | PATCH | /v1/asr/selection | Persist and activate an exact engine/model | | POST | /v1/asr/activate | Activate and persist an exact engine/model | | POST | /v1/asr/engines/{engineId}/setup | Install a managed runtime and pinned weights | | POST | /v1/asr/engines/{engineId}/models/{modelId}/pull | Pull one exact ASR model and validate its managed runtime | | POST | /v1/asr/engines/{engineId}/models/{modelId}/deploy | Pull, select, and activate one exact ASR model | | POST | /v1/asr/transcriptions · /v1/asr/test | Transcribe/test using the real selected backend | | GET | /v1/voice/asr-models | Compatibility registry alias | | POST | /v1/voice/asr-models/switch | Compatibility activation alias | | POST | /v1/voice/tts | Synthesize speech | | POST | /v1/audio/speech | OpenAI-compatible TTS alias | | GET | /v1/audio/classify/health | Jetson CUDA/TensorRT YAMNet readiness | | POST | /v1/audio/classify/setup | Provision and warm the pinned JetPack TensorRT YAMNet runtime | | POST | /v1/audio/classify | Direct-tool compatible CUDA audio classification | | GET | /v1/audio/embed/health | Role-typed embedding readiness (?kind=acoustic|speaker|semantic) | | POST | /v1/audio/embed/setup | Provision/warm one role-typed embedding runtime (admin; ?kind=...) | | POST | /v1/audio/embed | Managed role-typed audio embedding (?kind=...) | | GET | /v1/audio/diarization/live/readiness | Non-mutating managed Sortformer worker readiness | | POST | /v1/audio/diarization/live/setup | Verify and warm a local Sortformer runtime (admin) | | POST | /v1/audio/diarization/live | Managed live/session-local speaker-turn diarization | | POST | /v1/audio/diarization/live/cancel | Terminate live worker work and clear its queue | | GET | /v1/audio/diarization/reconcile/readiness | Non-mutating managed Community-1 worker readiness | | POST | /v1/audio/diarization/reconcile/setup | Verify and warm a local Community-1 runtime (admin) | | POST | /v1/audio/diarization/reconcile | Managed offline/dream reconciliation proposals | | POST | /v1/audio/diarization/reconcile/cancel | Terminate reconciliation work and clear its queue | | POST | /v1/voice/transcribe | Transcribe audio | | POST | /v1/voice/asr | Legacy transcription alias | | POST | /v1/audio/transcriptions | OpenAI-compatible transcription alias | | POST | /v1/voice/transcribe/stream | Isolated final transcription over SSE (no shared mic state or fake partials) | | POST | /v1/voice/clone-refs | Upload voice clone reference | | GET | /v1/voice/clone-refs | List clone references | | POST | /v1/voice/clone-refs/upload | Upload clone reference | | POST | /v1/voice/clone-refs/from-url | Fetch clone reference | | POST | /v1/voice/clone-refs/{filename}/activate | Activate clone reference | | POST | /v1/voice/clone-refs/{filename}/rename | Rename clone reference | | DELETE | /v1/voice/clone-refs/{filename} | Delete clone reference | | POST | /v1/voice/speak | Broadcast speech to voicechat clients | | GET | /v1/voicechat/ws | WebSocket upgrade for full-duplex voicechat | | POST | /v1/vision/describe | Vision describe placeholder | | GET | /v1/vision/embed/readiness | Non-mutating isolated OpenCLIP readiness | | POST | /v1/vision/embed/setup | Explicit isolated OpenCLIP setup (admin scope) | | POST | /v1/vision/embed | Create a vision embedding from media | | GET | /v1/ocr/readiness | Non-mutating advanced-OCR dependency and backend readiness | | POST | /v1/ocr/setup | Create and verify the isolated OCR venv (admin scope) | | POST | /v1/ocr/advanced | Agent-equivalent managed advanced OCR (alias of /v1/tools/ocr_image_advanced/call) |

POST /v1/voice/tts and /v1/audio/speech automatically warm the daemon. An explicit model must render exactly or the request fails; Omnius does not silently synthesize with another voice. Responses include X-Voice-Model, X-Voice-Backend, and X-Sample-Rate. Available models include GLaDOS, Overwatch, luxtts:announcer-testchamber03, and the selected Voicebox suite. Set OMNIUS_VOICEBOX_MODELS=all for every carried-in Voicebox model, leave it at stable for the default set, or provide a comma-separated subset.

ASR selection is independent from TTS selection. The registry currently exposes OpenAI Whisper, managed transcribe-cli, NVIDIA Nemotron (reported unavailable until its legacy bootstrap is migrated), and Microsoft VibeVoice ASR. VibeVoice uses the exact pinned microsoft/VibeVoice-ASR checkpoint, reports setup and activation separately, supports completed files up to 60 minutes with speakers, timestamps, and ?context= hotwords, and is deliberately not advertised as an incremental PCM backend. Its managed setup inherits the host CUDA-enabled Torch build (needed on Jetson/ARM64), never installs generic PyPI Torch, and activation requires one explicit capable GPU. Discrete Linux uses nvidia-smi process/GPU evidence; Jetson/L4T uses NVIDIA's documented tegrastats plus CUDA Torch device properties because nvidia-smi is unavailable there. Model weights live under the unified Omnius ASR cache and are not shipped in the npm package.

Generative Media

All generation is backed by the unified ~/.omnius model store and shared venvs (single source of truth — no per-project duplication). Generated files are consolidated into the global gallery at ~/.omnius/media/{images,videos,audio,music}.

| Method | Path | Purpose | | --- | --- | --- | | GET | /v1/media/models | List available image/video/audio/music models | | GET | /v1/media/store | Unified store disk usage + reclaimable legacy caches | | POST | /v1/media/migrate | Dedup + migrate legacy per-group caches into the unified store | | POST | /v1/media/relocate | Relocate the whole media store (weights/venvs/gallery) to a chosen folder | | GET | /v1/media/relocate/status | Status + progress of the media-store relocation job | | POST | /v1/media/av/analyze | Analyze a media file into a grounded entity/event answer (AV comprehension) | | POST | /v1/media/image | Generate an image | | POST | /v1/media/video | Generate a video | | POST | /v1/media/audio | Generate a sound effect | | POST | /v1/media/music | Generate music | | GET | /v1/media/gallery | List previously generated media (global, newest first) | | GET | /v1/media/file | Stream one generated media file |

Managed TTS pull installs the model's runtime prerequisites and weights. It does not start inference. Managed TTS deploy also verifies the selected CUDA device and starts the persistent runtime. Both operations return 200 when ready, 404 when the model has no matching managed adapter, and 500 when installation, download, CUDA preflight, or startup fails.

ASR download requests use {engineId, modelId, device?}. A collection POST returns 200 when weights are ready or 202 with statusUrl, retryUrl, and pollAfterMs while work is pending. Duplicate work coalesces. Poll the model URL until its download is ready and its deployment is active. A missing job returns 404. Model-specific POST and retry requests return 200 when ready or 202 when accepted. The model pull and deploy routes accept optional {device}. Pull validates the managed runtime and CUDA placement. Deploy also persists the selection after readiness and returns a pollable 202 transition when activation is pending.

Engines And Scheduled Jobs

| Method | Path | Purpose | | --- | --- | --- | | GET | /v1/engines | Long-running engine status | | GET | /v1/services | List all active daemon-owned REST services and their routes | | GET | /v1/services/{id} | Get one daemon-owned REST service contract | | GET | /v1/scheduled | List scheduled jobs | | DELETE | /v1/scheduled/all | Delete all tasks, timers, cron entries, and persisted sources | | GET | /v1/scheduled/status | Scheduler status | | POST | /v1/scheduled/{id} | Enable or disable one scheduled task or user timer | | DELETE | /v1/scheduled/{id} | Delete one scheduled task or user timer | | POST | /v1/scheduled/kill | Kill scheduled job | | POST | /v1/scheduled/fixup | Reconcile scheduled state | | GET | /v1/scheduled/reconcile | Preview scheduled reconciliation | | POST | /v1/scheduled/reconcile | Preview or apply scheduled reconciliation | | GET | /v1/services/systemd | Systemd service status | | POST | /v1/services/systemd/{unit} | Act on one user-level systemd unit | | GET | /v1/update | Self-update status | | POST | /v1/update | Start an exact-version verified global update transaction |

GET /v1/services is the agent-readable service inventory generated from the OpenAPI document. Each entry states lifecycle ownership, interactive-session dependency, registered routes, and a readiness or status route when one exists. GET /v1/services/{id} returns one service contract or 404 for an unknown service ID. These discovery routes do not mutate services. /listen and /hangup control voice sessions only and do not own the REST daemon.

Verified Global Update Transaction

POST /v1/update is not a CLI-local package edit. It starts one durable transaction that installs the requested exact npm version globally, verifies the installed package and resolved omnius executable, restarts and verifies the daemon, verifies package/hash/runtime agreement, and relaunches the tray if it was running. The response is 202 with operation state; poll GET /v1/update for live phase, subprocess output, verification evidence, and the final success or failure. Concurrent transactions and requests with no available target return 409.

The web dashboard and native tray both use this same endpoint. Update discovery is shared and semver-aware, so an older cached registry result cannot downgrade or falsely present an update. A completed transaction means the global package, executable, daemon, and tray runtime were all reconciled—not merely that npm exited successfully.

AIMS Governance

| Method | Path | Purpose | | --- | --- | --- | | GET | /v1/aims | AIMS root and endpoint index | | GET | /v1/aims/policies | Policy register | | PUT | /v1/aims/policies | Replace policy register | | GET | /v1/aims/roles | Roles and responsibilities | | GET | /v1/aims/resources | Resource inventory | | GET | /v1/aims/impact-assessments | Impact assessments | | POST | /v1/aims/impact-assessments | File impact assessment | | GET | /v1/aims/lifecycle | Lifecycle state | | GET | /v1/aims/data-quality | Data quality controls | | GET | /v1/aims/transparency | Model cards and transparency | | GET | /v1/aims/usage | AIMS usage view | | GET | /v1/aims/suppliers | Supplier inventory | | GET | /v1/aims/incidents | Incident records | | POST | /v1/aims/incidents | File incident | | GET | /v1/aims/oversight | Human oversight gates | | GET | /v1/aims/decisions | Consequential decision log | | GET | /v1/aims/config-history | Config change history |

Browser And Compatibility Surfaces

The dashboard HTML routes (/, /chat, /agent, /voice, /generate, /projects, /dashboard, /jobs, /activity, /discover, /settings, and /config) are documented in the dashboard guide. They are pages, not JSON API operations; / returns the HATEOAS JSON root when the client does not request HTML.

Swagger/ReDoc trailing-slash variants, /api/docs/* static assets, and /favicon.ico exist for browsers. They are delivery details rather than stable integration endpoints. The daemon also retains browser/legacy bridges at /v1/model, /v1/endpoint, /v1/theme, /v1/tor/*, /v1/remote-proxy, and /v1/command. New clients should prefer /v1/config/model, /v1/config/endpoint, /v1/config, and /v1/commands/{cmd}. Compatibility handlers may accept additional HTTP verbs for old dashboard bundles; only the methods in the supported inventory above are contractual.

Agent-Explorable Documentation

Omnius discovers project-local docs skills from .aiwg/addons/*/skills. The docs bundles in this repo expose high-signal entrypoints for agents:

/skills omnius docs
skill_execute name="omnius-docs"
skill_execute name="omnius-rest-docs"
skill_extract name="omnius-realtime-docs" query="How does realtime REST mode work?"

The intended pattern is index first, targeted document second, not loading the whole manual into the active context.

Development

pnpm install
pnpm -r build
pnpm docs:check

Focused checks used for the docs skill surface:

pnpm --filter @omnius/execution exec vitest run tests/skill-discovery.test.ts
pnpm --filter omnius exec vitest run tests/realtime-mode.test.ts tests/command-registry.test.ts

Publishing

Publish only from publish/.

cd omnius
pnpm -r clean || true
find . -name 'tsconfig.tsbuildinfo' -not -path '*/node_modules/*' -delete
pnpm -r build
node scripts/build-publish.mjs
cd publish
mkdir -p .npm-cache
NPM_CONFIG_CACHE=$(pwd)/.npm-cache npm pack --prefer-online --cache-min=0 --registry https://registry.npmjs.org/
NPM_CONFIG_CACHE=$(pwd)/.npm-cache npm publish --access public --prefer-online --cache-min=0 --registry https://registry.npmjs.org/

Before publishing, verify README.md, package.json, dist/index.js, and dist/launcher.cjs are in the tarball, and that package.json includes readmeFilename: "README.md" plus a string readme.

License

Omnius is released under CC-BY-NC-4.0 for non-commercial use. Commercial use, redistribution, hosted services, and enterprise deployment require a commercial license.