Omnigent: one harness for many agent CLIs

What Omnigent is

Omnigent is an open source meta-harness: one orchestration layer that drives the agent command line tools (CLIs) you already have installed. It does not replace Claude Code, Codex, Cursor, OpenCode, Hermes or Pi. It starts them, gives each one a job, and supervises the result inside a single session with one policy set. Databricks published the repository in June 2026 under the Apache 2.0 licence, and the front page still reads Status: alpha.

The practical claim is narrow, and worth stating plainly. You describe an agent once, in YAML, and you name the harness that runs it. Change that one line and the same agent runs on a different vendor's CLI. Nothing else in your setup changes, because Omnigent owns the loop above the agents rather than the loop inside them.

What is a meta-harness, and how is it different from a framework?

A harness is the program that wraps a model in a loop. It reads your prompt, calls tools, edits files and reports back. Claude Code is a harness. Codex is a harness. You install it, you log in, and it works on its own.

A framework is a library you write code against. You import it, you define the steps in Python, and your program becomes the agent. Changing vendor there means editing your code, because the vendor's client is wired through your program.

A meta-harness sits one level up from both. It is a supervisor that runs harnesses as child processes. Omnigent starts the vendor CLI, hands it work, and reads what comes back. You keep the CLI you already installed, and you keep whatever subscription or API (application programming interface) key already pays for it. That is the whole difference, and it decides who the tool is for: people with several agent CLIs already working, who are tired of driving them one terminal at a time.

What problem does one orchestration layer solve?

• Switching vendor costs one line. The agent definition holds harness and model as data, so moving a role from one vendor to another is an edit to the YAML file, not a rewrite.
• Review can cross vendors. A diff written by one model gets read by a model from a different company. Two models from the same family tend to share the same blind spots, so a second opinion from the same vendor is worth less.
• Policy has one home. Spend caps and approval prompts are declared in the agent file, and they apply to every sub-agent underneath it.
• The session outlives any one tool. One transcript covers work done by several CLIs, so you can read back what happened without stitching four scrollbacks together.

The cost is the layer itself. Every bug in Omnigent is now a bug sitting between you and an agent that used to work on its own. At alpha that is a real cost, not a theoretical one.

Where a multi-agent harness fits next to single agent tools

If you have not yet run one agent on a server, start there instead. Our guide to running a coding agent on a VPS covers the single agent case end to end, and that is the setup Omnigent assumes you already have. The wider field of self-hosted AI agents is where you pick the agents themselves, and learning how agents actually work is the better first stop if the vocabulary here is new.

Omnigent is also a different axis from a connector layer. Work like giving agents access to your own data sources is about what an agent can reach. Omnigent is about which agent runs, in what order, under what limits. You can want both at once, and they do not overlap.

What you need before you install

• Python 3.12 or newer. The published package declares requires-python >= 3.12.
• tmux, because the terminal harnesses run inside it.
• At least one vendor CLI, already installed and already logged in.
• Node.js 22 only if you build from a git checkout. The wheel on PyPI ships the built web assets, so the normal install needs no Node at all.

Install a pinned release, not main

curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh -s -- --version 0.7.0

The sh -s -- part is not decoration. Without it, sh reads --version as its own option and the installer never sees the flag, so you get whatever is newest that day. On a repository shipping breaking changes every few weeks, that is the difference between a reproducible box and a surprise.

The installer uses uv, Astral's Python package manager, and offers to install uv first if it is missing. If uv is already there, skip the script:

uv tool install --force --python 3.12 "omnigent==0.7.0"

Extras follow the same pattern, and the flag repeats: --extra e2b --extra kubernetes on the script, or "omnigent[e2b,kubernetes]" with uv. Note that the git tag is v0.7.0 while the package version on PyPI is 0.7.0.

uv puts the binary in the directory uv tool dir --bin reports, usually ~/.local/bin, and the installer offers to append that to your shell profile. If the command is not found straight after a clean install, that is why. Check what you ended up with:

omni upgrade --check

That compares the installed version against the latest published one and tells you whether an upgrade exists, without performing it. omni and omnigent are the same program under two names.

Point it at a model provider

omni setup

The wizard looks for credentials already present in your environment and prompts for the ones missing. It handles API keys, vendor subscriptions, gateways such as OpenRouter or Ollama, and Databricks workspaces. If you already run a local model server with Ollama on the same machine, point a gateway at that and the traffic never leaves the box.

A minimal multi-agent run

The example agents live in the repository, so clone the same tag you installed rather than main.

git clone --depth 1 --branch v0.7.0 https://github.com/omnigent-ai/omnigent.git
cd omnigent
omnigent run examples/polly/

Polly is the multi-agent coding orchestrator that ships with the repo. Its config declares sub-agents named claude_code, codex, opencode, cursor, hermes and pi, and one rule that makes the whole exercise worth running: review is always done by a different vendor than the implementer. Polly writes no code itself. It plans, splits the goal into work items, delegates each one, and routes each diff to a reviewer from another vendor.

Before delegating anything, Polly runs a preflight check to see which sub-agent CLIs actually exist on the machine. With only one vendor CLI installed there is nobody to hand the diff to, so install at least two before you judge the output. Debby, the other shipped example, is a debate agent with two heads, one Claude and one GPT:

omni debby

It is a short way to confirm two providers are configured, because it needs both to say anything.

Sub-agents are declared as tools

The agent file is YAML. executor names the harness, the model and the authentication. tools holds MCP (model context protocol) servers, Python functions, and sub-agents. A sub-agent is a tool with type: agent and an executor of its own, which is the mechanism behind everything above.

name: orchestrator
prompt: |
  You coordinate coding and review tasks.

executor:
  harness: claude-sdk
  model: databricks-claude-sonnet-4-6

tools:
  coder:
    type: agent
    prompt: Write and test code.
    executor:
      harness: claude-sdk
      model: databricks-claude-opus-4-7
  reviewer:
    type: agent
    prompt: Review proposed changes.
    executor:
      harness: claude-sdk
      model: databricks-claude-sonnet-4-6

omnigent run path/to/my_agent.yaml

Those model ids come from the project's own docs/AGENT_YAML_SPEC.md example, and they are Databricks-hosted names. Replace harness and model with whatever omni setup configured on your box. Other harness values in the spec include antigravity, copilot, kimi, qwen, and acp:<slug> for anything speaking the generic protocol. The spec also supports pass_history: true on a sub-agent, which hands it the parent conversation. That costs tokens on every delegation, so leave it off for sub-agents that only need the task in front of them.

Why long running orchestration belongs on a VPS

A multi-agent run is not a two minute command. Plan, delegate, wait on parallel git worktrees, review, revise. Closing a laptop lid ends all of it. A VPS (virtual private server) stays up and keeps its network, so the session survives while you are not watching.

omnigent server --background
omnigent server status

The server hosts a web user interface on port 6767. omnigent server status reports whether one is running, and omnigent stop shuts it down. In releases before v0.7.0 this was omni server start, which was removed, so older write-ups and screenshots will not match what your terminal does.

Do not publish 6767 on a public address. Two shapes are safe. Keep the port closed at the firewall and forward it over SSH with ssh -N -L 6767:localhost:6767 you@your-server, then open the web interface at http://localhost:6767 on your own machine. Or terminate TLS (transport layer security) in front of it and turn authentication on:

OMNIGENT_AUTH_ENABLED=1 omnigent server --background

The firewall half of that is ordinary work, covered in the ufw firewall basics for a VPS, and if the box already runs containers behind Traefik in front of several Docker Compose apps then Omnigent is one more service in the same pattern.

For a container deploy, the repository's deploy/ directory holds a Compose setup: ./bootstrap.sh mints secrets into .env, then docker compose up -d starts Omnigent and Postgres on port 6767. DATABASE_URL selects Postgres or SQLite, and OMNIGENT_AUTH_ENABLED defaults to 1 inside the containers, which is the right default for anything reachable from outside.

On sizing, the deploy notes put the server's working set at roughly 512 MB to 1 GB, and the Fly.io config pins 1 GB. That figure is the supervisor alone. Every sub-agent is a separate process holding its own checkout and its own model client, so size the box for the agents. Once a server is up, omnigent login https://your-host followed by omnigent host https://your-host registers your laptop against it, and omnigent attach <session_id> picks a running session back up from another device.

Sandbox every sub-agent before you walk away

Omnigent ships an operating system level sandbox called Omnibox. On Linux it uses bubblewrap namespaces plus seccomp, so the kernel enforces the boundary rather than the agent's prompt. A prompt-injected agent cannot talk its way out of a kernel rule. Install the dependency first:

sudo apt install bubblewrap

The configuration lives under os_env in the agent file:

os_env:
  type: caller_process
  cwd: .
  sandbox:
    type: linux_bwrap
    write_paths: [.]
    write_files: []
    read_paths: []
    allow_network: true
    cwd_allow_hidden: [.venv]
    env_passthrough: []
    egress_rules: []
    credential_proxy: []

The working directory is read only until you list it in write_paths, so an agent that goes wrong cannot write outside the workspace. Dotfiles stay hidden unless named in cwd_allow_hidden, which means a broad read grant does not quietly expose .ssh or .aws. Set egress_rules and all HTTP and HTTPS traffic goes through a default deny proxy, with each rule written as "METHODS host/path-glob". credential_proxy goes one step further: the agent only ever holds a placeholder, and the proxy swaps in the real secret as the request leaves, so a leaked transcript leaks nothing usable. In a multi-harness setup each sub-agent carries its own sandbox block in its own config file under agents/, so a reviewer can be denied the network while the implementer keeps it.

The limit is stated in the documentation, and it matters. The OS sandbox applies to sys_os_* tool calls and to terminals. It does not cover MCP servers, and it does not cover the Omnigent supervisor process itself. An MCP server you started runs outside the box with your permissions. That gap is why the stronger pattern is still one throwaway machine per agent, which is the subject of running coding agents in a disposable VM. The other half of the job is credentials, and keeping secrets out of an agent's reach gets harder, not easier, when six sub-agents share one host.

Spend limits are policies, declared in the same file:

policies:
  budget:
    type: function
    handler: omnigent.policies.builtins.cost.cost_budget
    factory_params:
      max_cost_usd: 5.00
      ask_thresholds_usd: [1.00, 3.00]

A run that plans with one vendor, implements with a second and reviews with a third is spending in three places at once, so set the cap before the first unattended run rather than after the first invoice. The built-ins also include max_tool_calls_per_session and ask_on_os_tools, which asks for approval before file and shell operations. Our notes on keeping AI agent costs under control on a VPS apply directly here, and they apply harder, because parallel sub-agents multiply the burn rate.

How fast is this repository moving?

[
  {
    "version": "v0.2.0",
    "released": "2026-06-19",
    "interval": 3
  },
  {
    "version": "v0.3.0",
    "released": "2026-06-27",
    "interval": 8
  },
  {
    "version": "v0.4.0",
    "released": "2026-07-03",
    "interval": 6
  },
  {
    "version": "v0.5.0",
    "released": "2026-07-10",
    "interval": 7
  },
  {
    "version": "v0.5.1",
    "released": "2026-07-10",
    "interval": 0
  },
  {
    "version": "v0.6.0",
    "released": "2026-07-21",
    "interval": 11
  },
  {
    "version": "v0.7.0",
    "released": "2026-07-27",
    "interval": 6
  }
]

Those are the published release dates from the project's own releases page, read on 3 August 2026. 7 tagged releases landed between 2026-06-19 and 2026-07-27, and the longest gap between any two was 11 days. v0.5.1 shipped the same day as the release before it. The first release, 0.1.1 on 16 June 2026, is left out of the chart because there is no previous tag to measure from.

Two of those releases broke commands that guides had already documented. v0.7.0 removed omni server start in favour of omni server --background. v0.6.0 renamed the omnigent[memory] extra to omnigent[hindsight], so an install line copied from a June write-up fails on a July build. This is the argument for --version in your install command and for a tag in your git clone, not a style preference.

What I would not trust it with yet

As of August 2026 the repository carries about 8.1k stars, 1.2k forks and roughly 350 open issues, with a first public release seven weeks old. Stars measure interest, and interest is not maturity. The project says alpha, and the release history above shows it means alpha.

• I would not run it on a host that holds production credentials, because the sandbox does not cover MCP servers or the supervisor.
• I would not leave a run unattended without a cost_budget policy, because three vendors can bill in parallel and nothing else stops them.
• I would not expose the server on a public IP address without OMNIGENT_AUTH_ENABLED set and TLS in front of it.
• I would not treat the agent YAML as stable across minor versions yet, so pin the version and read the release notes before upgrading.

One more thing to know before it surprises you: v0.6.0 added anonymised usage telemetry, and the project documents it on a dedicated telemetry page. Read that page and make your decision deliberately if the machine handles client work.

What Omnigent is genuinely good at today is the thing it was built for. You have three or four agent CLIs, you already pay for them, and you want one of them to write while another reviews. That works now, on one machine, with real sandboxing on Linux. Treat everything past that as promising and unfinished.

FAQ

Is Omnigent an agent, or a thing that runs agents?

It runs agents. Omnigent is a meta-harness: it starts the vendor CLIs you already installed, such as Claude Code, Codex or OpenCode, gives each one work, and supervises the results in one session. It brings no model of its own. This is why it is different from a framework, where you write Python against a library and your own program becomes the agent.

Do I need Claude Code and Codex installed before Omnigent is useful?

You need at least one vendor CLI installed and logged in, because Omnigent drives those programs rather than replacing them. For the shipped Polly example you want two or more from different vendors. Polly's rule is that review is always done by a different vendor than the implementer, so with a single CLI present there is no second vendor to send the diff to.

How do I install a specific Omnigent version instead of the latest?

Pass --version through the install script with sh -s --, as in sh -s -- --version 0.7.0. Without -s -- the flag is consumed by sh itself and the script installs the newest release. With uv already present, uv tool install --force --python 3.12 "omnigent==0.7.0" does the same job. The git tag is v0.7.0 while the PyPI version string is 0.7.0.

Is the Omnibox sandbox enough to run agents unattended?

It is strong for what it covers and clear about what it does not. On Linux it uses bubblewrap plus seccomp, so the kernel enforces file and network limits and the agent cannot opt out. The documentation states that it applies to sys_os_* tool calls and terminals, and that it does not cover MCP servers or the Omnigent supervisor process. An MCP server therefore runs with your normal permissions, which is why a disposable virtual machine per agent remains the stronger isolation for unattended work.

How much memory does an Omnigent server need on a VPS?

The project's deploy notes give the server a working set of roughly 512 MB to 1 GB, and its Fly.io configuration pins 1 GB. That covers the supervisor and the web interface on port 6767 only. Each sub-agent is a separate process with its own working copy and model client, and Polly-style runs use parallel git worktrees, so size RAM and disk for the number of agents you plan to run at once rather than for the server.