Omnigent Quickstart: Orchestrate Claude Code, Codex & Pi

Omnigent is Databricks’ open-source meta-harness — a single layer that runs above Claude Code, Codex, Cursor, Pi, and agents you write yourself. Instead of juggling one tool per terminal, you get one CLI, one set of guardrails, and one shareable session. In this tutorial you’ll install Omnigent, run your first agent, define a custom one in YAML, add cost and approval policies, and share a live session a teammate can co-drive.

Heads up: Omnigent is in alpha (Apache-2.0). It moves quickly, so commands and config may shift between releases. Everything here matches the June 2026 release. When in doubt, check the official quickstart.

Prerequisites

You’ll need a few things on your machine first:

• Python 3.12+
• Node.js 22 LTS or newer, with npm
• tmux (macOS/Linux) — Omnigent uses it to manage agent sessions
• git
• Linux only: bubblewrap (bwrap), used for sandboxing
• Optional: the Databricks CLI, if you want to use Databricks workspace models

On Windows, run everything inside WSL2 — there’s no native Windows support yet.

Step 1: Install Omnigent

The quickest path is the official install script:

curl -fsSL https://omnigent.ai/install.sh | sh

Prefer a package manager? Any of these work too:

uv tool install omnigent          # via uv (recommended for Python tooling)
pip install "omnigent"            # via pip
brew install omnigent-ai/tap/omnigent   # via Homebrew

If you plan to use Databricks workspace models, install the extra:

uv tool install "omnigent[databricks]"

The installer puts a CLI on your PATH. You can invoke it as omni (short form, used throughout this guide) or omnigent (long form) — they’re the same tool.

Confirm it’s installed:

omni --version

Step 2: Configure your credentials

Omnigent needs to know how to reach a model. Run the setup wizard:

omni setup

The wizard detects credentials already in your environment and prompts for anything that’s missing. Omnigent accepts several kinds:

Kind	Example
API key	An Anthropic or OpenAI key
Subscription	Claude Pro/Max or a ChatGPT plan, via the official CLIs
Gateway	Any OpenAI- or Anthropic-compatible base_url
Databricks	A workspace profile

That gateway option is handy. To route everything through OpenRouter, point the harnesses at:

• Claude Code → https://openrouter.ai/api
• Codex / OpenAI agents → https://openrouter.ai/api/v1

Or run fully local against Ollama with http://localhost:11434/v1.

Step 3: Run your first agent

Omnigent ships with a built-in demo agent called Debby. Start it:

omni debby

This launches a local server and prints a URL — by default http://localhost:6767 (it falls back to the next free port if 6767 is taken). Open that URL in your browser and you’ve got a live agent session with full history, running in the web UI.

Want a specific harness instead of the demo? These all work:

omni            # interactive — pick a model/harness from a menu
omni claude     # a Claude Code agent
omni codex      # a Codex agent

There’s also Polly, a multi-agent orchestrator example, which is a great way to see several agents coordinate. You’ll run it as a custom agent in the next step.

Step 4: Define a custom agent in YAML

The real power shows up when you describe your own agent in a file. Create agent.yaml:

name: data_analyst
prompt: You are a helpful data analyst.

executor:
  harness: claude-sdk   # codex, claude-native, cursor, openai-agents, pi…

tools:
  word_count:
    type: function
    callable: mypackage.mymodule.word_count

  researcher:
    type: agent
    prompt: Search for relevant information and summarize it.
    tools:
      word_count: inherit

Three things to notice:

• executor.harness is the only line you change to switch engines. Valid values include claude-sdk, claude-native, codex, codex-native, cursor, openai-agents, and pi. Your prompt and tools stay put.
• Function tools (type: function) point at a Python callable by dotted path.
• Sub-agents (type: agent) let one agent call another as a tool — here, researcher is itself an agent that inherits the word_count tool. That’s how you compose multi-agent systems.

Run it:

omni run path/to/agent.yaml

To run the bundled multi-agent example:

omni run examples/polly/

Step 5: Add guardrails with policies

Before you let an agent loose on a real repo, give it boundaries. Omnigent enforces policies at the meta-harness layer — outside the model — so they can’t be prompted away, and they can reason about what’s happened earlier in the session.

Add a policies block (at the server, agent, or session level):

policies:
  approve_shell:
    type: function
    handler: omnigent.policies.builtins.safety.ask_on_os_tools

  cap_calls:
    type: function
    handler: omnigent.policies.builtins.safety.max_tool_calls_per_session
    factory_params:
      limit: 50

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

What these do:

• approve_shell — pauses for human approval before the agent runs OS-level tools.
• cap_calls — hard-stops a runaway agent after 50 tool calls in a session.
• budget — checks in at $3.00 and won’t cross $5.00 without your go-ahead.

Policies apply in layers — server-wide → per-agent → per-session — and the strictest matching rule is checked first. Built-in contextual policies can also key off session state: a common pattern is requiring approval to git push only after the agent has installed a new npm package. For network-level isolation, Omnigent’s Omnibox sandbox can hide secrets like a GitHub token from the agent and inject them only into approved outbound requests.

Step 6: Run a server and collaborate

So far you’ve been running locally. To make sessions shareable, start the server explicitly:

omni server start    # runs in the background at http://localhost:6767
omni server status   # check it's up
omni stop            # stop all services

In the web UI, hit Share on a session to get a live link with full history. A teammate can review it, comment on files in the agent’s workspace, and steer the agent. From their own terminal they can:

omni attach <session_id>      # co-drive the same session
omni run --fork <session_id>  # branch the conversation onto their machine

Running a server for a team? Turn on multi-user auth:

OMNIGENT_AUTH_ENABLED=1 omni server start

Sign in as admin in the web UI’s admin panel and invite teammates with single-use links. For SSO, point OMNIGENT_OIDC_ISSUER at your provider (Google, GitHub, Okta, or Microsoft).

Step 7: Deploy it somewhere (optional)

When you’re ready to host Omnigent beyond your laptop, the repo’s deploy/README.md covers Docker Compose, Render, Fly.io, Railway, Modal, and Hugging Face Spaces. For compute, agent sessions can run in cloud sandboxes via Modal, Daytona, or Islo. And if you’d rather not run any of it yourself, Omnigent on Databricks (Beta) gives you a managed server wired into Unity AI Gateway and Databricks Sandboxes — with the trade-off that only built-in policies are supported.

Keeping it updated

omni upgrade          # update to the latest release
omni upgrade --check  # just check whether an update exists

To silence the periodic update notice, set OMNIGENT_NO_UPDATE_CHECK=1.

Troubleshooting

• omni: command not found — the install script couldn’t write to your PATH. Reopen your shell, or reinstall with uv tool install omnigent and make sure ~/.local/bin is on your PATH.
• Port 6767 already in use — Omnigent automatically falls back to the next free port; check the URL it prints rather than assuming 6767.
• Sandbox errors on Linux — install bubblewrap (bwrap); it’s required for OS-level sandboxing.
• Nothing happens on Windows — run inside WSL2. There’s no native Windows build yet.
• Model auth failing — re-run omni setup; for gateways, double-check the base_url matches the harness (Claude Code and the OpenAI-style agents use different paths).

Frequently asked questions

Do I have to use Databricks to run Omnigent? No. The open-source project runs entirely on your own machine. Omnigent on Databricks is a separate, optional managed offering.

Can I mix different models in one system? Yes — that’s the point. Each agent (and sub-agent) sets its own executor.harness, so a single orchestrated system can run several models at once.

Is it production-ready? Treat it as alpha. It’s genuinely useful for experimentation and team workflows today, but expect breaking changes and keep a human in the loop on anything destructive.

Where do policies actually run? At the meta-harness layer, not inside the model’s prompt — which is exactly why an agent can’t negotiate its way past them.

Wrapping up

You’ve installed Omnigent, run a built-in agent, authored a custom one in YAML, fenced it in with cost and approval policies, and shared a live session a teammate can co-drive. The mental shift worth keeping: in a meta-harness, your policies, sessions, and skills are the durable assets — they travel with you no matter which model or harness is running underneath.

From here, read the architecture write-up in our companion piece, Databricks Omnigent: The Open-Source Meta-Harness for AI Agents, and explore the GitHub repository for the full policy catalog and deployment guides.