README
¶
Research. Code. Write. Automate. Browse. Analyze. — five named agents that hand off to each other and remember what you discussed.
Or have Ava build entirely new agents for tasks nobody's imagined yet. You run the team. Ava grows the team.
It all runs on your own machine — no cloud account, no subscription, no data leaving your box except the calls to the AI model you choose.
New here? → Get started in 10 minutes · How it works · Use the web app · Use the terminal
What can Omnipus do?
People install Omnipus to get things done, not to study the architecture. Out of the box, your team can:
✓ Build applications with a team of coding agents
✓ Research a topic and get back a cited report
✓ Create a custom expert agent in minutes — no prompt engineering
✓ Automate browser workflows with approval gates
✓ Remember decisions across sessions and projects
✓ Run entirely on your own machine — your keys, no telemetry
What you actually get
A team, not a chatbot
Five named agents who hand work to each other in the same conversation — Mia hears your request, picks the right teammate, and passes control over.
No copy-paste, no re-explaining.
They delegate and parallelize
Agents can plan work and assign tasks to each other — track it all on the Command Center board — and break a big job into parallel subagents that report back.
Memory that learns
When a conversation winds down, Omnipus writes a recap and records the lessons learned — what went well, what to improve.
The recap carries into your next session automatically, and the lessons are kept for recall, so your team builds on past work instead of starting cold.
Agents that know your preferences
Tell them once in Settings → Profile ("be concise", "I use Python", your timezone) and every agent keeps it in mind.
→ Tell your agents your preferences
Reach them anywhere
Use the web app, the terminal, or wire your agents into Telegram, Discord, Slack, WhatsApp, and 10 other chat platforms — voice notes and images included.
→ Channels
You stay in control
Agents ask permission before running anything sensitive (Allow / Deny / Always), and every action is logged so you can see exactly what happened.
→ When an agent asks permission
Extend it
Install reusable skills, connect MCP servers, and let Ava build brand-new custom agents for you on demand.
Your keys, your machine
API keys are encrypted on disk, nothing phones home, and there's no telemetry.
Pick from 35+ AI providers — including fully-local options like Ollama.
For the technically curious — what's under the hood
Single Go binary — ~30 MB, with the web app embedded. No database, no Redis; file-based storage at ~/.omnipus/.
Kernel-level sandbox — Landlock + seccomp on Linux 5.13+, a three-tier per-tool policy (allow/ask/deny), and an SSRF guard on every outbound HTTP tool. → Sandbox modes
Encrypted credential vault — AES-256-GCM with an Argon2id KDF. → Cryptographic design
Full audit trail — every tool call, LLM request, and agent event lands in a replayable on-disk transcript that feeds the UI, subprocess hooks, and a tamper-evident audit log. → Session transcript
14 in-process chat channels and 35+ LLM providers — with fallback chains, multi-key rotation, streaming, and vision. → Channels · Providers
Channel-to-agent routing — binds inbound messages to specific agents by channel, account, guild, team, or peer. → Inbound bindings
Meet the team
Five named coworkers ship with every install.
Their identity is locked — no silent knock-offs — but you control each one's model and tool policy.
| Agent | Role | Best at |
|---|---|---|
| Mia | Coach & Guide | Onboarding new users, routing requests to the right teammate by intent — not by name. |
| Jim | General Purpose | Hands-on implementation: writing code, creating files, scoping projects, coordinating across agents. |
| Ava | Agent Builder | Interviews you, then creates a brand-new custom agent — persona, tools, prompt — in seconds. |
| Ray | Researcher | Deep research with citations. Web search, fetch, synthesis. Refuses to bluff when evidence is thin. |
| Max | Automator | Browser automation. Plan-then-execute multi-step flows with approval gates. |
Need more? Ava builds unlimited custom agents, and Omnipus runs them all in the same binary.
See it work
Four live screenshots, captured against the running gateway.
Mia routes by intent
Tell her what you need — "I need an agent to help me build a marketing website" — and she picks the right teammate, says why, and hands off in 12 ms.
The receiving agent picks up in the same transcript. No copy-paste.
Ray researches with sources
Web searches fan out, and the results synthesise into a numbered list with citations.
He won't fake an answer.
Max sees the web
browser.navigate → browser.screenshot, chained in one turn.
The image streams back through the media pipeline and renders inline.
Ava builds an agent live
Tell her what you need, watch her call system.agent.create, and get a summary card.
The new agent shows up in the roster instantly.
Install
Find your platform below. Most people want the one-line install; Windows and Intel-Mac users run Omnipus in Docker for now.
| Your system | Do this |
|---|---|
| Linux (x86-64 or ARM64) | One-line install |
| macOS (Apple Silicon — M1/M2/M3/M4) | One-line install |
| macOS (Intel) | Run in Docker — no native binary yet |
| Windows | Run in Docker — native app in progress |
Once it's running, continue to First boot.
Linux and macOS (Apple Silicon)
curl -sSL https://raw.githubusercontent.com/elicify-ai/omnipus/main/scripts/install.sh | sh
omnipus start
# open http://localhost:5000
The same command works on Linux (x86-64 or ARM64) and Apple-Silicon Macs — it auto-detects your system and downloads the right build. (On macOS you may need to approve the binary the first time under System Settings → Privacy & Security.)
Under the hood, the script detects your OS and architecture (uname -s / uname -m), downloads the matching omnipus_<OS>_<arch>.tar.gz from the latest GitHub Release, and verifies its SHA256 against the published checksums.txt.
It then extracts a single ~30 MB self-contained Go binary (SPA embedded via go:embed, no shared-lib runtime) to /usr/local/bin/omnipus.
It's plain POSIX sh — no bash-isms — so it runs on Alpine, BusyBox, macOS, and Ubuntu.
Customise via environment:
| Variable | Default | Purpose |
|---|---|---|
OMNIPUS_VERSION |
latest Release |
Pin a tag, e.g. OMNIPUS_VERSION=v0.1.0 |
OMNIPUS_INSTALL_DIR |
/usr/local/bin |
Use $HOME/.local/bin if you don't have sudo |
OMNIPUS_REPO |
elicify-ai/omnipus |
Override only for forks |
Browser tools. On the first browser.navigate / browser.screenshot / web_serve call, the gateway looks for google-chrome / chromium / chromium-browser on $PATH. If one is found it's used as-is; if not, a managed Chromium is downloaded to $OMNIPUS_HOME/browser/chromium/ (Chrome for Testing, ~150 MB, one-time).
That download needs glibc, so on Alpine hosts install chromium via apk first — the PATH lookup then resolves and the managed download is skipped.
Supported platforms in v0.1: Linux amd64, Linux arm64, macOS arm64 (Apple Silicon). Other targets are tracked in platform support.
Windows and Intel macOS
We don't ship a native binary for these platforms yet, so the smooth path is Docker.
Windows — a native Windows app is on the roadmap and actively being worked on. Until it ships, run Omnipus in Docker.
Intel Macs — there's no prebuilt Intel binary in v0.1 (it's deferred to v0.1.1). Use Docker, or build from source.
For both, we recommend the full (heavy) Docker image: it bundles browser automation and Python MCP support, so you get complete feature parity — nothing is missing. The build-and-run commands are in Docker, heavy image just below. If you only need chat and channels and don't care about in-app browsing, the smaller published image starts with a single docker run.
Docker, minimal image
docker run -d \
-p 127.0.0.1:5000:5000 \
-p 127.0.0.1:5001:5001 \
-v "$PWD/data:/root/.omnipus" \
ghcr.io/elicify-ai/omnipus:latest
Or with compose: curl -O https://raw.githubusercontent.com/elicify-ai/omnipus/main/docker/docker-compose.yml && docker compose up.
The published image (ghcr.io/elicify-ai/omnipus:latest) is built from docker/Dockerfile: an Alpine multi-stage build that produces a ~71 MB runtime image with only ca-certificates, tzdata, and curl on top of the Go binary.
Same SPA, same channels, same memory + sessions + audit log as the native install.
Minimal image limitations
The minimal image deliberately excludes Chromium to keep the artefact small. As a result:
All browser.* tools (navigate, screenshot, read_content, console_logs, action) and the entire web_serve preview flow will not work out of the box.
The auto-download fallback in pkg/tools/browser/manager.go does fetch a managed Chromium from Chrome for Testing — but that binary is glibc-linked while the runtime is Alpine (musl), so exec fails with a misleading no such file or directory. (The missing piece is the ELF interpreter /lib64/ld-linux-x86-64.so.2, not the binary itself.)
The Max agent gracefully falls back to web_fetch for read-only tasks and explains the missing capability to the user.
If you need browser tools inside Docker, use the heavy image below.
Docker, heavy image
docker build -t omnipus:heavy -f docker/Dockerfile.heavy .
docker run -d \
-p 127.0.0.1:5000:5000 \
-p 127.0.0.1:5001:5001 \
-v "$PWD/data:/home/omnipus/.omnipus" \
omnipus:heavy
Built from docker/Dockerfile.heavy: the same three-stage SPA + Go build as the minimal image, but the runtime stage adds chromium, python3, py3-pip, uv / uvx, git, jq, and a global agent-browser npm install.
About 1.08 GB on disk, in exchange for first-class browser tools and Python MCP server support out of the box.
Heavy image is not currently published to GHCR — build it yourself per the snippet above. (Tracked: ship it from the same release pipeline.)
From source (contributors)
git clone https://github.com/elicify-ai/omnipus.git
cd omnipus
make build # builds SPA + Go binary in one step
./build/omnipus start
Requires Go 1.26+ and Node 24+. make build runs spa-embed first so go:embed picks up the latest Vite output.
First boot
Two ports open: 5000 serves the SPA + API, and 5001 serves sandboxed agent preview iframes.
The onboarding wizard runs on first visit: Welcome → Provider → API Key → Model → Admin Account → Done.
A 256-bit AES key auto-generates at ~/.omnipus/master.key (mode 0600).
Back it up — losing it means losing every encrypted credential.
For headless deployments, pre-provision the key via OMNIPUS_KEY_FILE or OMNIPUS_MASTER_KEY. → Credential encryption
Headless onboarding (no browser)
If you can't open localhost:5000 — Docker host, remote VPS, CI runner — finish onboarding from the shell instead. Secrets are read from stdin so they never appear in ps:
printf '%s\n%s\n' "$OPENROUTER_API_KEY" "$ADMIN_PASSWORD" | \
omnipus onboard --non-interactive \
--provider openrouter \
--api-key-stdin \
--model 'z-ai/glm-5v-turbo' \
--admin-username admin \
--admin-password-stdin
omnipus start
omnipus onboard --help lists every flag (--provider, --api-key, --api-key-stdin, --model, --admin-username, --admin-password, --admin-password-stdin, --non-interactive).
It applies the same end-state mutations as the SPA wizard — config, credentials, admin user, state — so you can log in immediately with the credentials you just passed.
Documentation
→ Full documentation index — every guide, grouped by what you're trying to do.
New here? Start with:
- Your first 10 minutes — install → first chat → handoff → build an agent
- How Omnipus works — agents, sessions, memory, channels, skills (plain English)
- Using the web app · Using the terminal
- Channels — connect Telegram / Discord / Slack / … and choose which agent answers each
Architecture
Single Go binary. File-based JSON/JSONL storage at ~/.omnipus/. No Postgres, no Redis.
WhatsApp uses pure-Go SQLite (modernc.org/sqlite) in its own session namespace.
Tech stack
Backend: Go 1.26+ · chromedp · whatsmeow · discordgo · telebot · slack-go · golang.org/x/sys/unix (Landlock, seccomp).
Frontend: TypeScript · React 19 · Vite 6 · shadcn/ui (Radix + Tailwind v4) · AssistantUI · Phosphor Icons · Zustand · TanStack Query/Router.
Status
Pre-1.0 and moving fast:
| Release | Status | Scope |
|---|---|---|
| v0.1 | ✅ Complete | Stabilized gateway, iframe preview, sandbox hardening |
| v0.2 | ✅ Complete | Security hardening |
| v0.3 / 1.0 | 🚧 In design | The "Rooms" redesign of memory, projects, and tasks |
A single Go binary with the web app embedded is the product — MIT-licensed, community-focused, no telemetry. See the roadmap.
Contributing
Issues, PRs, and discussions are all welcome.
| If you want to… | Go to |
|---|---|
| Find live work | open issues |
| Ask a question | SUPPORT.md |
| Set up to build | CONTRIBUTING.md |
| Understand community expectations | CODE_OF_CONDUCT.md |
| Report a vulnerability | SECURITY.md |
| Sign the CLA (before your first PR) | Contributor License Agreement |
| Dig into internal context — BRDs, ADRs, specs, designs | internal documentation |
The Omnipus name and logo are reserved per the trademark policy.
License
MIT · omnipus.ai
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
omnipus
command
|
|
|
omnipus-launcher-tui
command
|
|
|
omnipus-launcher-tui/config
Package config provides types and I/O for ~/.omnipus/tui.toml.
|
Package config provides types and I/O for ~/.omnipus/tui.toml. |
|
omnipus/internal/audit
Package audit provides the `omnipus audit` subcommand.
|
Package audit provides the `omnipus audit` subcommand. |
|
omnipus/internal/credentials
Package credentials provides the `omnipus credentials` subcommand.
|
Package credentials provides the `omnipus credentials` subcommand. |
|
omnipus/internal/doctor
Package doctor implements the `omnipus doctor` command, which performs pre-flight configuration safety checks per US-15.
|
Package doctor implements the `omnipus doctor` command, which performs pre-flight configuration safety checks per US-15. |
|
omnipus/internal/onboard
Package onboard provides the interactive `omnipus onboard` CLI wizard.
|
Package onboard provides the interactive `omnipus onboard` CLI wizard. |
|
evals
|
|
|
cmd/eval-runner
command
eval-runner is the Omnipus LLM-as-judge eval harness.
|
eval-runner is the Omnipus LLM-as-judge eval harness. |
|
judge
Package judge provides the LLM-as-judge prompt template and scoring logic for the Omnipus eval harness.
|
Package judge provides the LLM-as-judge prompt template and scoring logic for the Omnipus eval harness. |
|
agent/envcontext
Package envcontext provides the "new-office onboarding" preamble that sits above an agent's identity in the system prompt (Fix A, spec v7).
|
Package envcontext provides the "new-office onboarding" preamble that sits above an agent's identity in the system prompt (Fix A, spec v7). |
|
agent/testutil
Package testutil provides shared test infrastructure for all Plan-3 PRs.
|
Package testutil provides shared test infrastructure for all Plan-3 PRs. |
|
api/generated
Package generated provides primitives to interact with the openapi HTTP API.
|
Package generated provides primitives to interact with the openapi HTTP API. |
|
audit
Package audit implements structured security audit logging for Omnipus.
|
Package audit implements structured security audit logging for Omnipus. |
|
constants
Package constants provides shared constants across the codebase.
|
Package constants provides shared constants across the codebase. |
|
coreagent
Package coreagent defines the 5 built-in core agents for Omnipus per issue #45 (Core Agent Roster v1).
|
Package coreagent defines the 5 built-in core agents for Omnipus per issue #45 (Core Agent Roster v1). |
|
credentials
Package credentials implements the Omnipus encrypted credential store per BRD SEC-23/23a–e and Wave 1 user stories US-3, US-4, US-11, US-12.
|
Package credentials implements the Omnipus encrypted credential store per BRD SEC-23/23a–e and Wave 1 user stories US-3, US-4, US-11, US-12. |
|
datamodel
Package datamodel provides directory initialization and entity schema types for the Omnipus file-based data model per Appendix E of the BRD.
|
Package datamodel provides directory initialization and entity schema types for the Omnipus file-based data model per Appendix E of the BRD. |
|
docextract
Package docextract extracts plain text from uploaded document files so the agent loop can inject their content into the conversation context.
|
Package docextract extracts plain text from uploaded document files so the agent loop can inject their content into the conversation context. |
|
fileutil
Package fileutil provides file manipulation utilities.
|
Package fileutil provides file manipulation utilities. |
|
gateway/ctxkey
Package ctxkey defines typed context keys shared between the gateway package and its sub-packages (e.g.
|
Package ctxkey defines typed context keys shared between the gateway package and its sub-packages (e.g. |
|
identity
Package identity provides unified user identity utilities for Omnipus.
|
Package identity provides unified user identity utilities for Omnipus. |
|
notifications
Package notifications implements a file-based, per-user notification store for the scheduled-agent-autonomy feature (#264).
|
Package notifications implements a file-based, per-user notification store for the scheduled-agent-autonomy feature (#264). |
|
onboarding
Package onboarding implements first-launch detection and onboarding state management per BRD Wave 5b user stories US-7 and US-8.
|
Package onboarding implements first-launch detection and onboarding state management per BRD Wave 5b user stories US-7 and US-8. |
|
pairing
Package pairing implements device pairing with admin approval per Phase 3A. Pairing flow: device generates Ed25519 key pair → 6-digit code + fingerprint → admin approves in browser.
|
Package pairing implements device pairing with admin approval per Phase 3A. Pairing flow: device generates Ed25519 key pair → 6-digit code + fingerprint → admin approves in browser. |
|
policy
Package policy implements the declarative security policy engine for Omnipus.
|
Package policy implements the declarative security policy engine for Omnipus. |
|
providers/bedrock
Package bedrock provides a stub implementation when built without the bedrock tag.
|
Package bedrock provides a stub implementation when built without the bedrock tag. |
|
providers/common
Package common provides shared utilities used by multiple LLM provider implementations (openai_compat, azure, etc.).
|
Package common provides shared utilities used by multiple LLM provider implementations (openai_compat, azure, etc.). |
|
providers/openai_responses_common
Package openai_responses_common provides shared utilities for providers that use the OpenAI Responses API (e.g., Azure, Codex).
|
Package openai_responses_common provides shared utilities for providers that use the OpenAI Responses API (e.g., Azure, Codex). |
|
sandbox
Package sandbox provides kernel-level and application-level process sandboxing.
|
Package sandbox provides kernel-level and application-level process sandboxing. |
|
security
Package security — prompt injection defenses (SEC-25).
|
Package security — prompt injection defenses (SEC-25). |
|
session
Package session provides day-partitioned JSONL session storage per Appendix E §E.5 and Wave 1 user story US-5.
|
Package session provides day-partitioned JSONL session storage per Appendix E §E.5 and Wave 1 user story US-5. |
|
skills
Package skills — MCP tool registration bridge.
|
Package skills — MCP tool registration bridge. |
|
sysagent
Package sysagent implements the Omnipus built-in system agent per BRD Appendix D. It uses the user's configured LLM provider and exposes the 41 system.* tools for managing agents, channels, providers, skills, config, diagnostics, and more.
|
Package sysagent implements the Omnipus built-in system agent per BRD Appendix D. It uses the user's configured LLM provider and exposes the 41 system.* tools for managing agents, channels, providers, skills, config, diagnostics, and more. |
|
sysagent/tools
Package systools implements the 41 exclusive system.* tools for the Omnipus system agent per BRD Appendix D §D.4.
|
Package systools implements the 41 exclusive system.* tools for the Omnipus system agent per BRD Appendix D §D.4. |
|
testutil
Package testutil provides shared performance-test orchestration helpers for the Omnipus load and SLO test suites.
|
Package testutil provides shared performance-test orchestration helpers for the Omnipus load and SLO test suites. |
|
tools/browser
Package browser implements browser automation tools using chromedp (pure Go CDP).
|
Package browser implements browser automation tools using chromedp (pure Go CDP). |
|
utils
Package utils provides shared, reusable algorithms.
|
Package utils provides shared, reusable algorithms. |
|
validation
Package validation provides cross-package input validators.
|
Package validation provides cross-package input validators. |
|
scripts
|
|
|
gen-asyncapi-go
command
Command gen-asyncapi-go generates Go structs from AsyncAPI 3 component schemas.
|
Command gen-asyncapi-go generates Go structs from AsyncAPI 3 component schemas. |