Databricks Data + AI Summit 2026

Omnigent: three ways to set it up

Omnigent is Databricks' open-source agent "meta-harness." It sits on top of your coding agents (Claude Code, Codex, Gemini and others) and routes each prompt to the right agent or model for the task. This guide walks the three ways to stand it up, from a laptop to a managed workspace.

Open source Routes across agents & models

Omnigent Meta-Harness. Agents (left) run on a Runner/host, coordinated by the Server (center), surfaced through many UIs (right). The three tiers below map onto this picture.

First, the one idea that explains all three methods

Omnigent splits into three tiers. The split is what makes "where do I run it" a real choice rather than a single install. Keep this picture in mind and every method below makes sense.

Server

The control plane and web UI. Accepts prompts, stores sessions, routes work. It does not run any agent itself.

Runner / Host

A machine running omni host. This is where agents actually execute, using your local provider CLIs (e.g. the claude CLI).

Sandbox

Optional disposable cloud host (Modal, Daytona, E2B and others) for execution that is not your own machine.

prompt → server routes → host or sandbox executes → result streams back

Pick your setup

Start with Method 1 to learn the moving parts on your own machine, then move to a shared cloud server (Method 2). Method 3 is the fully managed path, still largely in preview.

When to use this

You want to try Omnigent on your own machine with the least moving parts. The server, the host, and the agents all run on your laptop. Nothing is exposed to anyone else. This is the best way to learn the model before deploying to the cloud.

Install the Omnigent CLI

Install with uv as a tool. This puts both omni and omnigent on your PATH at ~/.local/bin.

# requires uv >= 0.11.8
uv tool install omnigent

# confirm it is on PATH
omni --version

Point it at a coding agent you already have

The host runs agents using your locally installed provider CLIs, not a cloud model endpoint. If you have the Claude Code CLI signed in to your subscription, Omnigent can drive it directly. Your providers live in ~/.omnigent/config.yaml:

host:
  name: mac
providers:
  claude:
    cli: claude        # the local Claude Code CLI
    default: !!bool 'true'
    kind: subscription

A kind: subscription provider just means "a logged-in CLI on this machine." Omnigent then routes prompts across whichever agents you have configured.

Add more agents (Codex, Gemini)

Each extra agent is one more subscription entry. The only prerequisite is that its CLI is installed and logged in on this machine. Omnigent detects a logged-in Codex CLI from ~/.codex/auth.json, so an empty or logged-out file does not count.

First, make sure the CLI is signed in:

# install + log in to the Codex CLI (one-time)
codex login

# sanity check: this file should exist and be non-empty
ls -la ~/.codex/auth.json

Option A, let Omnigent detect it (recommended): the setup flow scans for ambient credentials and adds any logged-in CLI it finds.

omni setup

Option B, add it by hand: append a block under providers: in ~/.omnigent/config.yaml. Keep default: true on exactly one provider.

providers:
  claude:
    cli: claude
    default: !!bool 'true'   # the default agent
    kind: subscription
  codex:
    cli: codex               # requires `codex login`
    kind: subscription
  gemini:
    cli: gemini              # requires the Gemini CLI logged in
    kind: subscription

Apply the change

omni host reads this config at startup. If a host is already running, Ctrl-C it and re-run omni host. The new agent then appears in the web UI alongside Claude Code.

Verify: python3 -c "import yaml; print(yaml.safe_load(open('$HOME/.omnigent/config.yaml'))['providers'].keys())" should list every agent you added.

Start the local server

Run the control plane on your machine. It opens a local web UI where you chat and watch sessions. State is kept locally (a SQLite chat.db mirror), so there is nothing to provision.

# starts the server + web UI on localhost
omni serve

# then open the printed URL, e.g. http://localhost:8080

Heads up

Exact subcommands can shift between CLI versions. If omni serve is not present in your build, run omni --help to find the local-server command. The two-tier idea (a server plus a host) is the part that does not change.

Attach a host so agents can run

In a second terminal, attach your machine as a host. The server can now hand work to it. Keep this terminal open: omni host is a foreground process and Ctrl-C disconnects it.

omni host

You should see: "Connected as 'mac', listening for sessions" and one or more "Runner started" lines. The web UI now lists a live agent, and a chat session executes real work on your machine.

That's the whole local loop

Server + host + agent, all on one laptop. Once this feels natural, Method 2 is the same host command pointed at a server that lives in the cloud instead of on localhost.

Server in the cloud, host on your machine

The server runs as a Databricks App. The host stays on your machine and attaches over the internet, so agents execute locally while the server and its state live in the workspace. You log in once with omnigent login, then attach the host with omni host (Step 3).

Deploy the server with the official bundle

Omnigent ships a Databricks bundle at deploy/databricks/ (databricks.yml + deploy.py + grant_sp_perms.py). It creates a Lakebase project for state and a UC Volume for artifacts, then deploys the App with header auth.

# from the omnigent repo, using your Databricks CLI profile
cd deploy/databricks
uv run --extra databricks deploy.py --profile <your-profile>

The bundle stands up an app backed by a Lakebase project for state and a UC Volume for artifacts, and runs the state migrations for you.

Clear the Free Edition gotchas

Each of these can trip up a Free Edition deploy, and each has a one-line fix. Apply them before deploy.

The six fixes that get the bundle to deploy

uv version: needs uv >= 0.11.8.
Databricks extra: run with uv run --extra databricks, else import databricks.sdk fails at runtime.
Compute size: SMALL is invalid in the current SDK. Use MEDIUM.
Catalog name: it is workspace, not main.
Telemetry: drop the telemetry_export_destinations block (Free Edition default storage rejects it).
Web UI build: the tsc build fails on @types/react v19 ("Cannot find namespace 'JSX'"). Either set OMNIGENT_SKIP_WEB_UI=true (API only, 3.4 MB wheel) or add import type { JSX } from "react" to the two flagged components. The full SPA then lands at a 9.71 MB wheel, just under the 10 MB Apps cap.

Attach your host to the cloud server

This is the step that makes the App executable. The host is not part of the deployed App, you run it on your own machine and point it at the App URL. Log in once, then attach the host.

# 1. Log in to the Databricks-fronted server (once per token lifetime).
#    It reads the workspace from the server and runs a browser OAuth login.
omnigent login https://omnigent-<workspace-id>.aws.databricksapps.com

# 2. Attach your machine as a host. It connects and auto-starts runners.
omni host --server https://omnigent-<workspace-id>.aws.databricksapps.com

After step 3: "Connected as 'mac', 0 live runner(s). Listening for sessions" plus "Runner started" lines. The web UI Agents panel shows a live "Claude Code" agent and a chat session executes real work against the workspace.

How the auth works

Databricks-fronted detection: Omnigent probes the server. A 302 whose location points at the workspace /oidc/...authorize endpoint tells it this is a Databricks App, and the redirect names the workspace.
omnigent login runs databricks auth login --host <workspace> (browser U2M OAuth), verifies the token against <server>/v1/me, then stores a pointer record in ~/.omnigent/auth_tokens.json: it saves the workspace host but no bearer token, because Databricks OAuth tokens expire after about an hour.
Token minting on demand: every later omni command mints a fresh workspace OAuth bearer from that cached grant. The Apps edge accepts the fresh, valid token and the tunnel connects.
When you log in again: the pointer holds no bearer, so the CLI re-mints on every call. When the cached grant lapses, run omnigent login to refresh it. In practice: log in once, then omni host works until the grant lapses.

Want execution off your Mac?

Run omni host on any always-on box (a small VM or a cloud sandbox) with the omni CLI and your provider CLIs installed. It attaches the exact same way: omnigent login once, then omni host. Same server, different host.

Mostly behind previews today

This is the fully managed path: Omnigent running natively in your workspace with no local host process. It is the cleanest experience and the clear direction of travel, but as of now most of it sits behind enablement previews. Good things to come.

What "managed" gives you

Native workspace identity (no manual OAuth juggling), a Databricks-provided Sandbox host so agents execute in the cloud, and no omni host process to keep alive on your laptop. The server and the execution capacity both live in the workspace.

New: create a Sandbox from the CLI (Beta)

Databricks now documents a serverless Sandbox you can create and SSH into directly. When you connect, the Databricks CLI is pre-installed and authenticated, and it auto-configures coding harnesses such as Claude and Codex to use AI Gateway (when AI Gateway is configured for your workspace). That is the same kind of cloud execution capacity the managed path uses, reachable from the CLI.

databricks sandbox create      # create your sandbox
databricks sandbox register    # optional: register SSH keys
databricks sandbox ssh         # SSH into your sandbox

Beta, and not yet tested here. It needs the feature preview enabled in your workspace, and per the Databricks docs, home-directory data is deleted when the beta ends. Treat it as forward-looking until you verify it yourself. Docs →

Requirements (enterprise account)

You need an enterprise Databricks account (Azure or AWS) and two previews enabled. These are account- and workspace-level toggles, so an account admin usually has to flip them.

Gated on

AI Gateway V2 at the account level (preview).
Omnigent at the workspace level (preview).

Until both are on, the managed Sandbox host is not selectable, which is why the local-host paths (Methods 1 and 2) are the usable options today.

Enable it

Once the previews are live for your account, you enable Omnigent from the workspace admin settings / previews panel, then open it directly in the workspace. No bundle deploy and no local host.

Today's practical advice

If you do not yet have these previews, you are not blocked. Deploy the server as a Databricks App (Method 2) and attach a local or VM-based host. When the managed previews land, you can move the execution into the workspace Sandbox without changing how you use the product.

Which one should you pick?

	1 · Local	2 · Databricks App	3 · Managed
Server runs	Your laptop	Databricks App (cloud)	In the workspace
Agents execute on	Your laptop	Your machine or a VM	Workspace Sandbox
Keep a terminal open?	Yes	Yes (the host)	No
Shareable with a team	No	Yes	Yes
Account needed	None	Free Edition is enough	Enterprise (Azure / AWS)
Status today	Works	Works	Preview

Omnigent is an open-source project. Exact CLI subcommands and bundle paths can shift between versions, so check the project repository for the latest. The two-tier idea (a server plus a host) does not change.