Metadata-Version: 2.4
Name: omnigent
Version: 0.20.0
Summary: Omnigent: declarative agent authoring and runtime framework
Author: Databricks, Inc.
Keywords: agents,llm,ai,databricks,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: omnigent-client==0.20.0
Requires-Dist: omnigent-ui-sdk==0.20.0
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: json5<1,>=0.10
Requires-Dist: openai<2.45,>=1.0
Requires-Dist: rich<16,>=14
Requires-Dist: prompt_toolkit<4,>=3.0
Requires-Dist: mcp<2,>=1.0
Requires-Dist: starlette<2,>=1.0.1
Requires-Dist: uvicorn[standard]<1,>=0.30
Requires-Dist: websockets<15,>=10.4
Requires-Dist: httpx<1,>=0.27
Requires-Dist: ftfy>=6.0
Requires-Dist: psutil<8,>=5.9
Requires-Dist: cel-python>=0.5
Requires-Dist: keyring<26,>=24
Requires-Dist: pillow<14,>=12.2
Requires-Dist: tomlkit<1,>=0.12
Requires-Dist: alembic<2,>=1.0
Requires-Dist: anyio<5,>=4.0
Requires-Dist: cachetools<8,>=5.0
Requires-Dist: filelock>=3.0
Requires-Dist: click<10,>=8.0
Requires-Dist: fastapi<1,>=0.100
Requires-Dist: pexpect<5,>=4.9; platform_system != "Windows"
Requires-Dist: pyte<1,>=0.8; platform_system != "Windows"
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: sqlalchemy<3,>=2.0
Requires-Dist: zstandard<1,>=0.22
Requires-Dist: tiktoken<1,>=0.7
Requires-Dist: opentelemetry-api<2,>=1.20
Requires-Dist: claude-agent-sdk>=0.1.62
Requires-Dist: openai-agents>=0.0.17
Requires-Dist: PyJWT[crypto]<3,>=2.8
Requires-Dist: argon2-cffi<26,>=23.1
Requires-Dist: packaging<27,>=23
Requires-Dist: certifi>=2026.10.19
Requires-Dist: protobuf<8,>=6
Requires-Dist: python-dateutil<3,>=2.8
Requires-Dist: tzdata>=2024.1; platform_system == "Windows"
Provides-Extra: claude-sdk
Provides-Extra: openai-agents
Provides-Extra: cockroachdb
Requires-Dist: psycopg[binary]<4,>=3.1; extra == "cockroachdb"
Requires-Dist: sqlalchemy-cockroachdb<3,>=2.0; extra == "cockroachdb"
Provides-Extra: all
Requires-Dist: databricks-sdk[sandbox]<1,>=0.153; extra == "all"
Requires-Dist: opentelemetry-sdk<2,>=1.20; extra == "all"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2,>=1.20; extra == "all"
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.20; extra == "all"
Requires-Dist: opentelemetry-instrumentation-fastapi<1,>=0; extra == "all"
Requires-Dist: opentelemetry-instrumentation-httpx<1,>=0; extra == "all"
Requires-Dist: opentelemetry-instrumentation-sqlalchemy<1,>=0; extra == "all"
Provides-Extra: bedrock
Requires-Dist: boto3<2,>=1.30; extra == "bedrock"
Requires-Dist: botocore<2,>=1.30; extra == "bedrock"
Provides-Extra: kms
Requires-Dist: boto3<2,>=1.30; extra == "kms"
Requires-Dist: botocore<2,>=1.30; extra == "kms"
Provides-Extra: s3
Requires-Dist: boto3<2,>=1.30; extra == "s3"
Requires-Dist: botocore<2,>=1.30; extra == "s3"
Provides-Extra: vertex
Requires-Dist: google-auth<3,>=2.0; extra == "vertex"
Provides-Extra: modal
Requires-Dist: modal<2,>=1.0; extra == "modal"
Provides-Extra: daytona
Requires-Dist: daytona<1,>=0.180; extra == "daytona"
Provides-Extra: blaxel
Requires-Dist: blaxel<0.5,>=0.4.1; extra == "blaxel"
Provides-Extra: boxlite
Requires-Dist: boxlite<1,>=0.9.5; extra == "boxlite"
Provides-Extra: microsandbox
Requires-Dist: microsandbox<0.7,>=0.6.9; extra == "microsandbox"
Provides-Extra: cwsandbox
Requires-Dist: cwsandbox<1,>=0.24; extra == "cwsandbox"
Provides-Extra: e2b
Requires-Dist: e2b<3,>=2.26; extra == "e2b"
Provides-Extra: islo
Requires-Dist: islo<0.4,>=0.3.5; extra == "islo"
Provides-Extra: openshell
Requires-Dist: openshell<1,>=0.1.0; extra == "openshell"
Provides-Extra: kubernetes
Requires-Dist: kubernetes<38,>=36; extra == "kubernetes"
Provides-Extra: vault
Requires-Dist: hvac<3,>=2; extra == "vault"
Provides-Extra: tracing
Requires-Dist: opentelemetry-sdk<2,>=1.20; extra == "tracing"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2,>=1.20; extra == "tracing"
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.20; extra == "tracing"
Requires-Dist: opentelemetry-instrumentation-fastapi<1,>=0; extra == "tracing"
Requires-Dist: opentelemetry-instrumentation-httpx<1,>=0; extra == "tracing"
Requires-Dist: opentelemetry-instrumentation-sqlalchemy<1,>=0; extra == "tracing"
Provides-Extra: agents-sdk
Requires-Dist: openai-agents<1,>=0.1; extra == "agents-sdk"
Requires-Dist: opentelemetry-instrumentation-openai-agents-v2>=0.1; extra == "agents-sdk"
Provides-Extra: antigravity
Requires-Dist: google-antigravity<1,>=0.1; extra == "antigravity"
Requires-Dist: protobuf<8,>=7; extra == "antigravity"
Provides-Extra: copilot
Requires-Dist: github-copilot-sdk<2,>=1; extra == "copilot"
Provides-Extra: dictation
Requires-Dist: sherpa-onnx<2,>=1.13; extra == "dictation"
Requires-Dist: sherpa-onnx-core<2,>=1.13; extra == "dictation"
Requires-Dist: numpy<3,>=1.24; extra == "dictation"
Provides-Extra: cursor
Requires-Dist: cursor-sdk>=0.1.7; extra == "cursor"
Provides-Extra: hindsight
Requires-Dist: hindsight-client>=0.4.0; extra == "hindsight"
Provides-Extra: nimble
Requires-Dist: nimble-python<2,>=1.2.0; extra == "nimble"
Provides-Extra: slack
Requires-Dist: omnigent-slack==0.20.0; extra == "slack"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]<4,>=3.1; extra == "postgres"
Provides-Extra: databricks
Requires-Dist: databricks-sdk[sandbox]<1,>=0.153; extra == "databricks"
Requires-Dist: opentelemetry-distro<1,>=0; extra == "databricks"
Requires-Dist: omnigent[postgres]; extra == "databricks"
Requires-Dist: pymysql<2,>=1.1; extra == "databricks"
Requires-Dist: databricks-mcp>=0.9.0; extra == "databricks"
Requires-Dist: databricks-ai-bridge>=0.19; extra == "databricks"
Provides-Extra: loadtest
Requires-Dist: locust<3,>=2.30; extra == "loadtest"
Dynamic: license-file

<div align="center">

# <img src="https://raw.githubusercontent.com/omnigent-ai/omnigent/main/docs/images/omnigent-logo.svg" alt="" height="38" valign="middle" /> Omnigent

### The open-source meta-harness for all your AI agents.

Omnigent is an open-source **meta-harness** that gives you a common orchestration layer over Claude Code, Codex, Cursor, OpenCode, Hermes, Pi, and the agents you write yourself: swap or combine harnesses without rewriting, enforce policies and sandboxing, and collaborate in real time from any device — terminal, browser, phone, or the native desktop app.

[![PyPI version](https://img.shields.io/pypi/v/omnigent.svg)](https://pypi.org/project/omnigent/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/omnigent-ai/omnigent/blob/main/LICENSE)
[![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/omnigent)
![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)

[omnigent.ai](https://omnigent.ai) · **[⬇️ Download the macOS desktop app](https://omnigent.ai/quickstart/install#install-the-desktop-app)**

</div>

<p align="center">
  <img src="https://raw.githubusercontent.com/omnigent-ai/omnigent/main/docs/images/omnigent-desktop.png" alt="The Omnigent desktop app: starting a new session, with pinned and project-grouped sessions in the sidebar" width="720" />
</p>

---

## Why Omnigent?

Omnigent lets you:

- **📱 Work with agents from any device, including your phone.** Sessions
  follow you: start in your terminal, continue in the browser, pick it up on
  your phone. Messages, sub-agents, terminals, and files stay in sync.

- **🤖 Supervise multiple agents.** Mix Claude Code, Codex, Cursor, OpenCode,
  Hermes, Pi, and custom agents (defined in YAML) together in the same
  session. Ask one agent to review another's work, or split a task across
  agents that are each good at different things.

- **🔌 Use any model.** A first-party API key, a Claude/ChatGPT subscription,
  or any compatible gateway. All first-class.

- **🤝 Collaborate.** Share a session so teammates can chat with your agent
  and watch it work live, co-drive it on your machine, or fork the
  conversation to continue on their own.

- **☁️ Run agents in cloud sandboxes.** No laptop required: run sessions in
  disposable [Modal](https://modal.com), [Daytona](https://www.daytona.io),
  [Blaxel](https://blaxel.ai),
  [Islo](https://islo.dev), [E2B](https://e2b.dev),
  [Gensee](https://gensee.ai),
  [CoreWeave](https://docs.coreweave.com/products/sandboxes),
  [Kubernetes](https://kubernetes.io), [OpenShell](https://github.com/NVIDIA/OpenShell),
  [Boxlite](https://github.com/boxlite-ai/boxlite),
  [microsandbox](https://github.com/superradcompany/microsandbox), or
  [Databricks](https://www.databricks.com) sandboxes, launched from the
  CLI or provisioned by the server per session (*managed hosts*).

- **🛡️ Govern your agents.** Create
  [policies](#6-govern-your-agents-with-policies) to pause for your approval
  before risky actions, cap spend, or limit which tools an agent reaches.
  They apply to the whole server, one agent, or a single chat.

---

## Quick start

### 1. Install

One command installs Omnigent and everything it needs:

```bash
curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh
```

The installer includes Databricks support and installs the Databricks CLI
alongside Omnigent, or reuses an existing CLI that supports workspace login.
Pass `--no-databricks` to omit them.

<details>
<summary>Optional integrations and extras</summary>

Need an optional integration? Pass one or more extras to the installer:

```bash
curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh -s -- --extra modal,e2b
```

The Antigravity SDK extra conflicts with Databricks dependencies. Install it
with `--no-databricks --extra antigravity`.

Available user-facing extras include:

- **Model providers:** `databricks` (included by default), `bedrock`, `vertex`
- **Sandbox providers:** `modal`, `daytona`, `blaxel`, `boxlite`, `microsandbox`,
  `cwsandbox`, `e2b`, `openshell`, `kubernetes`
- **SDK harnesses:** `antigravity`, `copilot`, `cursor`, `agents-sdk`
- **Storage and memory:** `s3`, `hindsight`

</details>

<details>
<summary>Prefer to install manually?</summary>

Omnigent needs **Python 3.12+**. Install the `omnigent` package:

```bash
uv tool install omnigent        # or: pip install "omnigent"
```

Manual installs use the same extras syntax, for example:

```bash
uv tool install "omnigent[databricks,modal]"
```

Or with [Homebrew](https://github.com/omnigent-ai/homebrew-tap):

```bash
brew install omnigent-ai/tap/omnigent
```

For source builds on networks that require package mirrors, replace these example
URLs with your mirrors:

```bash
HOMEBREW_PIP_INDEX_URL='https://pypi.example.com/simple' \
HOMEBREW_CARGO_INDEX_URL='https://cargo.example.com/index/' \
  brew install --build-from-source omnigent-ai/tap/omnigent
```

The PyPI setting also routes pip's isolated build dependencies through the mirror.
The Cargo setting takes a sparse registry index URL ending in `/`, without the
`sparse+` prefix. Both overrides are optional and do not affect prebuilt-bottle
installs.

Or install straight from the repo:

```bash
uv tool install -q --python 3.12 git+https://github.com/omnigent-ai/omnigent.git
```

</details>

<details>
<summary>Toolchain and prerequisites (if the installer reports a missing tool)</summary>

- **`uv`** (required). https://docs.astral.sh/uv/getting-started/installation/
  The installer offers to set this up for you.
- **`git`** (required).
- **Node.js 22 LTS or newer** with **`npm`** (for the coding-harness CLIs
  installed by `omnigent run`) and **`pnpm`** (for the web UI). You can get
  both from a single Node install; pnpm is available via
  `corepack enable` or `npm install -g pnpm`.
- **Devin CLI** (optional), for `omnigent devin`: install with
  `curl -fsSL https://cli.devin.ai/install.sh | bash`, then sign in with
  `devin auth login`. Devin tool approvals appear as Chat approval cards
  (its `PermissionRequest` hook is mirrored to the web UI) and stay
  answerable in the embedded Terminal. See `docs/devin-native.md`.
- **Kiro CLI** (optional), for `omnigent kiro`: install with
  `curl -fsSL https://cli.kiro.dev/install | bash`, then sign in with Kiro.
  Kiro tool approvals stay answerable in the embedded Terminal; supported
  one-time approvals also appear as Chat cards. See
  `docs/kiro-native-elicitation.md`.
- **`tmux`**, required by the native `omnigent <harness>` terminal wrappers
  (`claude`, `codex`, `cursor`, `devin`, `hermes`, `kiro`, `pi`)
  (`brew install tmux` / `apt install tmux`; the installer offers
  to install it for you).
- **`bubblewrap`** (`bwrap`), **Linux only**. The native `omnigent <harness>`
  terminal wrappers and the `pi` harness wrap each agent
  terminal in a `bwrap` OS-sandbox; on Linux that isolation is mandatory, so a
  missing `bwrap` binary makes those terminals fail to start
  (`apt install bubblewrap`; the installer offers to install it for you). macOS
  uses the built-in `seatbelt` sandbox and needs nothing extra.
- **Databricks.** The bootstrap installer includes the `databricks` extra
  and the Databricks CLI. If installing with uv directly, use
  `uv tool install "omnigent[databricks]"` and install the
  [Databricks CLI](https://docs.databricks.com/aws/en/dev-tools/cli/install)
  separately. Sign in to a workspace-hosted server with
  `omnigent login <workspace-url>/omnigent`.

</details>

<details>
<summary>Windows (native)</summary>

Omnigent runs natively on Windows in a degraded mode. The `install_oss.sh`
bootstrap is POSIX-only, so install with `uv` directly:

```powershell
uv tool install --python 3.12 omnigent
# or from the repo:
uv tool install --python 3.12 git+https://github.com/omnigent-ai/omnigent.git
```

What works on Windows: `omnigent server`, the web UI, and the SDK-based
harnesses (`omnigent run <agent.yaml>` with the claude-sdk / cursor / codex
harnesses). Agents run under a Windows **Job Object** for process-tree
containment.

What is **not** available on Windows (use Linux/macOS, or WSL, for these):

- the native `omnigent claude` / `omnigent codex` / `omnigent cursor`
  tmux/PTY terminal wrappers (run an SDK harness or the web UI instead);
- `bwrap`/`seatbelt` filesystem & network sandboxing and the L7 egress proxy
  — the Job Object backend contains the process tree and enforces resource
  limits but does **not** isolate the filesystem or network.

</details>

<details>
<summary>Updating to a new release</summary>

When a newer release is on PyPI, Omnigent shows a one-line notice (once per
release) pointing here. To update:

```bash
omni upgrade            # detects how you installed, drains & stops the local
                        # server, then runs the matching upgrade command
omni upgrade --check    # just report whether a newer release is available
```

`omni upgrade` waits for in-flight agent sessions to finish before stopping the
local server (pass `--force` to stop them immediately); the next `omni` command
brings the server back up on the new version. Source checkouts update with
`git pull` instead. Silence the notice with `OMNIGENT_NO_UPDATE_CHECK=1`.

The check queries your configured package index — honoring `UV_INDEX_URL` /
`PIP_INDEX_URL` and your `uv.toml` / `pip.conf` (default PyPI), so private
mirrors work out of the box; override with `OMNIGENT_INDEX_URL` if needed.

</details>

<details>
<summary>Uninstalling Omnigent</summary>

Preview the CLI/profile cleanup that would run by default:

```bash
omnigent uninstall
```

Remove the CLI and installer-managed PATH entries while keeping your local
history, credentials, and projects:

```bash
omnigent uninstall --yes
```

To also remove Omnigent state under `~/.omnigent`, pass `--purge`; Omnigent
backs it up outside the target before deletion. Your `~/omnigent` workspace is
kept unless you explicitly add `--purge-workspace`.

```bash
omnigent uninstall --purge --yes
```

If the installed wheel is broken or `omnigent` is not on `PATH`, run the
standalone script instead:

```bash
curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/uninstall_oss.sh | sh
```

Add `--yes` to the standalone script to perform the previewed CLI cleanup.

</details>

### 2. Start your first agent

`omnigent` picks a model with you and starts a session in your terminal. It
also launches a local web UI at `http://localhost:6767` that shows the same
session in the browser, or on a phone on your network (step 4). The
[desktop app](https://omnigent.ai/docs/interact/desktop) wraps that same UI
in a native window and adds OS notifications (with a configurable sound) and a dock badge —
[download it for macOS](https://omnigent.ai/quickstart/install#install-the-desktop-app).

> [!NOTE]
> The install puts two names for the same CLI on your PATH: `omnigent` and
> the shorter `omni`. They're interchangeable.

> [!TIP]
> On first run, Omnigent picks up model credentials already in your
> environment (an `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`, or a `claude` /
> `codex` CLI you're logged into) and offers one as the default.

```bash
omnigent
```

Or launch a specific agent runtime:

```bash
omnigent claude                      # Claude Code, in a session your team can join
omnigent codex                       # Codex
omnigent cursor                      # Cursor
omnigent agy                         # Antigravity
omnigent opencode                    # OpenCode
omnigent hermes                      # Hermes Agent (Nous Research)
omnigent pi                          # Pi
omnigent copilot                     # GitHub Copilot (SDK harness, via `omnigent run`)
```

`omnigent agy` requires agy 1.1.13 or newer. When `GEMINI_API_KEY` is set,
direct Gemini API authentication takes precedence over agy's saved OAuth login.

To configure native agy credentials, run `omni setup` →
**Antigravity** → **Configure native agy API key / gateway** → **Add a credential**
and choose the option matching your connection:

- **Gemini — API key** for a Google AI Studio key.
- **Gemini API gateway — URL + key** for an external gateway implementing native
  Gemini requests and `x-goog-api-key` authentication. Supply its API root, such
  as `https://gateway.example/gemini`, without `/v1beta` or a model operation.
- **Databricks — profile** for a Databricks workspace with native Gemini API
  access. Omnigent manages profile authentication and model-name mapping; no
  workspace URL or token needs to be pasted into the gateway form.

OpenAI Responses and Chat Completions endpoints are **not supported by native
agy**, even when they serve Gemini models. A separate protocol adapter would be
required. The first Gemini credential becomes the default; select **Make default
for Gemini** when switching, then start a fresh `omni agy` session.

See the [native agy gateway guide](docs/native-agy-gateways.md) for compatibility
requirements, model and authentication behavior, troubleshooting, and smoke
steps. These settings configure native agy; the Antigravity Python SDK retains
its separate key/Vertex setup.

Using OpenClaw? See the [OpenClaw integration guide](docs/openclaw.md) to import
its coding agents or drive a live OpenClaw Gateway session over ACP.

<details>
<summary>Grok Build and Devin</summary>

Two more coding agents are built in but have no `omnigent <name>` launcher of
their own, because each ships a CLI that holds its own login. Install the vendor
CLI, log in with it, then name the harness:

```bash
# Grok Build (xAI)
curl -fsSL https://x.ai/cli/install.sh | bash
grok login --device-auth              # xAI OAuth
omnigent run --harness grok           # 'grok-build' also works

# Devin (Cognition)
curl -fsSL https://cli.devin.ai/install.sh | bash
devin auth login
omnigent run --harness devin
```

Both speak the [Agent Client Protocol](https://agentclientprotocol.com) over
stdio, and Omnigent stores no credential for either — each CLI reads back the
login it wrote to disk. That also means `--model` is refused rather than
silently dropped: both run their account-default model. To pin one, configure an
`acp:` agent whose command passes the vendor's own model flag.

Use the vendor login rather than an API key. A builtin ACP row has no
`env_passthrough` of its own, and `XAI_API_KEY` is not in the host-to-runner
credential allowlist, so exporting it in your shell does not reach the agent.
If you need the key route, pass it explicitly with
`OMNIGENT_RUNNER_ENV_PASSTHROUGH=XAI_API_KEY`, or configure an `acp:` agent that
declares the passthrough.

</details>

#### 🐙 Polly and 🟠🔵 Debby

Two example agents ship with the repo, and they make good first sessions:

```bash
omnigent run examples/polly/
omnigent run examples/debby/
omnigent run examples/deep-research/

# ...or on a different harness (sub-agents keep their own):
omnigent run examples/polly/ --harness <harness>
omnigent run examples/debby/ --harness <harness>
```

**🐙 Polly** is a multi-agent coding orchestrator who writes no code herself.
She's the tech lead: she plans, delegates the work to coding sub-agents
(Claude Code, Codex, or Pi) in parallel git worktrees, then routes each diff
to a reviewer from a different vendor than the one that wrote it. You merge.

**🟠🔵 Debby** is a brainstorming partner with two heads, one Claude and one GPT.
Every question you ask goes to both heads, and she lays the two answers out
side by side. Type `/debate` and the heads critique each other for a few
rounds before converging. (She needs both a Claude and an OpenAI credential;
see step 3.)

**🔎 Deep Research** is a single agent that answers a question with a cited,
cross-checked report. It plans sub-queries, searches the live web and reads
full pages through an MCP search server, and verifies each claim across
independent sources. It's also the simplest example to copy from: one agent
plus one `tools/mcp/*.yaml` server, no sub-agents.

**Prefer the browser?** One command starts the local server and registers this
machine as a host:

```bash
omnigent start   # starts the local server and registers this machine as a host
```

Open the server URL it prints, hit **New Chat**, pick your machine, and go.
Check status with `omnigent server status`; stop everything with
`omnigent stop`.

Integrations can open the new-chat composer with text already filled in using
`/?prompt=Explain%20this%20code`. Build links with
`URLSearchParams` to preserve newlines, Unicode, and characters such as `&` and
`+`. For a deployment under `/tools/omnigent`, use
`/tools/omnigent/?prompt=Explain%20this%20code`.

The text is an editable draft: the user chooses a host and agent and presses
Send to start the session. The prompt parameter is removed from the current URL
after loading, while other query parameters and the fragment are retained.

To suppress the automatic browser tab, use `omni host --no-open` or set
`OMNIGENT_HOST_NO_OPEN=1` in your shell. Both also apply to `omni host
--background` and `omni start`. Sign-in may still open a browser; use
`--non-interactive` in scripts to fail if sign-in is required.

A session can also start itself: the **Automations** page runs an agent on a
recurring schedule. See the [automations guide](https://github.com/omnigent-ai/omnigent/blob/main/docs/AUTOMATIONS.md)
for the schedule format, the REST API, and the current limits.

<details>
<summary>Customize automatic session titles</summary>

Set additional natural-language requirements for the isolated title generator:

```bash
omnigent config set --global \
  'session_title_instructions=Prefix titles with the current date as lowercase mon-dd. Use PR-number-short-name for pull requests, issue-number-short-description for issues, and a short snake_case activity otherwise.'
```

The title generator receives the current date as `YYYY-MM-DD`, then applies
these requirements to the first user message. The setting is server-owned and
does not alter an agent's portable instructions. Default generated titles are
limited to 100 characters; custom title requirements may use up to 200.
Default titles over 100 characters are rejected, leaving the first-message
fallback title in place. Custom titles over 200 characters are truncated with
a trailing ellipsis. Manually assigned titles are also limited to 200
characters. The setting applies after the local Omnigent server restarts, both
to new sessions and to later agent-initiated renames through `sys_session_rename`.
Agent proposals are formatted using the same title requirements; if formatting
fails, the existing title is preserved. Manual renames remain unchanged.
For longer instructions, edit `~/.omnigent/config.yaml` directly and use a YAML
block scalar:

```yaml
session_title_instructions: |
  Prefix every title with the current date as lowercase mon-dd.
  For pull requests use mon-dd-PR-number-short-name.
  For issues use mon-dd-issue-number-short-description.
  For other work use mon-dd-short_snake_case_activity.
```

Server operators can set the same key in the YAML passed to
`omnigent server --config`.

Claude Code sessions generate titles with the `haiku` model alias. If that
model answers the message instead of returning a title, set
`OMNIGENT_BACKGROUND_TITLE_CLAUDE_MODEL` to another Claude model alias, such as
`sonnet`, in the environment of the `omnigent` or `omnigent host` process that
runs the session.

</details>

### 3. Choose & switch models

```bash
omnigent setup
```

Add a credential, set a default, or remove one, grouped by agent. Omnigent
works with four kinds of credentials:

| | Kind | What it is |
|---|---|---|
| 🔑 | **API key** | A first-party vendor key for Anthropic, OpenAI, and similar providers |
| 🎟️ | **Subscription** | A Claude Pro/Max or ChatGPT plan, via the official `claude` / `codex` CLIs |
| 🌐 | **Gateway** | Any OpenAI- or Anthropic-compatible `base_url` and key (OpenRouter, LiteLLM, Ollama, vLLM, Azure) |
| 🧱 | **Databricks** | A Databricks workspace profile (requires the `databricks` extra) |

Defaults are per agent, so a Claude default and a Codex default coexist. You
can also switch models in the middle of a session with the `/model` command.

<details>
<summary>Gateway base URLs (OpenRouter, Ollama)</summary>

When you add a **Gateway** credential, `omnigent setup` asks for a base URL
and a key. The base URL depends on which agent you point it at:

| Provider | For | Base URL | Key |
|---|---|---|---|
| **OpenRouter** | Claude Code | `https://openrouter.ai/api` | your OpenRouter key (`sk-or-…`) |
| **OpenRouter** | Codex / OpenAI agents | `https://openrouter.ai/api/v1` | your OpenRouter key (`sk-or-…`) |
| **Ollama** (local) | Codex / OpenAI agents | `http://localhost:11434/v1` | any value (Ollama ignores it) |

For Claude Code, point at OpenRouter's Anthropic-compatible endpoint
(`…/api`, **not** `…/api/v1`). For Codex and the OpenAI-agents harness, use
the OpenAI-compatible `…/api/v1`.

</details>

### 4. Deploy a server (and use it from your phone📱)

Run Omnigent on a server with a stable URL
([`deploy/README.md`](https://github.com/omnigent-ai/omnigent/blob/main/deploy/README.md) is the full guide) and your sessions
become reachable from anywhere, including your phone. The web UI is built for
mobile, so you get the same chat, sub-agents, terminals, and files, in sync
with your laptop.

One `docker compose up` runs the server on any host you have (a VPS, a home
server); **Render** and **Railway** deploy with one click; **Fly.io**, **Hugging
Face Spaces**, **Modal**, **Cloudflare** (serverless, scale-to-zero), and
**Databricks Apps** (backed by Lakebase Postgres and Unity Catalog Volumes) are
covered too — and a **Cloudflare quick tunnel** (public) or **Tailscale**
(private) reaches a server running on your own laptop without a deploy. The
server can also provision a cloud sandbox per session (*managed hosts*), so no
laptop has to stay online. The full menu of targets, the database options, the
sandbox setup, and
[branding/white-labeling](https://github.com/omnigent-ai/omnigent/blob/main/deploy/README.md#branding-white-labeling)
live in
[`deploy/README.md`](https://github.com/omnigent-ai/omnigent/blob/main/deploy/README.md).

Once the server is up, sign in and register your laptop as a host:

```bash
omnigent login https://your-host    # sign in once; run / attach / host reuse the token
omnigent host  https://your-host    # new sessions can now run on this machine
```

> [!TIP]
> On your own network you don't need a deploy. Open your machine's LAN
> address on your phone (e.g. `http://192.168.x.x:6767`).

### 5. Collaborate with your team

Omnigent supports **multi-user accounts**, controlled by one environment
variable:

```bash
OMNIGENT_AUTH_ENABLED=1 omnigent server --background
```

The **Docker deploy in [step 4](#4-deploy-a-server-and-use-it-from-your-phone)
turns it on for you** (`OMNIGENT_AUTH_ENABLED` defaults to `1` there).

#### Invite your teammates

Open the web UI (`http://localhost:6767` locally, or your host's URL) and
sign in as `admin`; first run prints the password and saves it locally. Then
open **Admin → Members → Invite** to create a single-use invite link, no
email server needed. Send it over; your teammate opens it, sets a password,
and they're in. Signup is invite-only.

<!-- TODO: screenshot of Admin → Members → Invite. -->

> [!NOTE]
> Teammates need to be able to reach the server. A local server is only
> reachable on your network; for anyone off it, deploy an always-on host
> (see [step 4](#4-deploy-a-server-and-use-it-from-your-phone)).

#### Code together

- **Share a live session.** Hit **Share** in the web UI and send the link;
  teammates watch your agent work and chat with it in real time.
- **Share with everyone who can sign in.** Admins can allow public Edit in
  **Settings > Sharing > Maximum public permission**. Owners then choose
  **Share > General access > Edit**. The default stays Read.
- **Leave a shared session.** Done with a session someone shared with you?
  Pick **Leave session** from its sidebar row menu to drop it from your
  sidebar. Nothing is deleted — the owner keeps it and can share it again.
- **Co-drive.** A teammate co-attaches to your running session; their
  messages execute on **your** machine. Great for pairing or handing the
  keyboard to a domain expert mid-investigation.

  ```bash
  omnigent attach <session_id>
  ```

- **Fork.** Clone a conversation onto your own machine and continue
  independently from the fork point.

  ```bash
  omnigent run --fork <session_id>
  ```

> [!TIP]
> Want your team to sign in with the logins they already have (**Google,
> GitHub, Okta, Microsoft**)? Set `OMNIGENT_OIDC_ISSUER` plus a client ID
> and secret on your deployed server and restart. The full walkthrough,
> domain allowlists, and the proxy-only `header` auth mode are covered in
> [`deploy/README.md#auth`](https://github.com/omnigent-ai/omnigent/blob/main/deploy/README.md#auth).

### 6. Govern your agents with policies

**Policies** decide what an agent may do: run shell commands, edit files,
spend tokens. They check every action and either allow it, block it, or pause
to ask you first.

- **In the web UI**: open a session's info panel to browse the available
  policies and toggle them on or off.
- **In chat**: ask. *"Add a policy that asks me before running shell
  commands."* The agent sets it up for you.

Want defaults that apply to everyone, or to a specific agent? Define them in
your server config or an agent's YAML:

```yaml
policies:
  approve_shell:
    type: function
    handler: omnigent.policies.builtins.safety.ask_on_os_tools   # ask before shell / file writes
  cap_calls:
    type: function
    handler: omnigent.policies.builtins.safety.max_tool_calls_per_session
    factory_params:
      limit: 50                    # cap how many tools one session can call
  budget:
    type: function
    handler: omnigent.policies.builtins.cost.cost_budget
    factory_params:
      max_cost_usd: 5.00           # hard spend cap...
      ask_thresholds_usd: [3.00]   # ...with a soft warning on the way
```

Policies stack across three levels, **server-wide** (admin), **per-agent**
(developer), and **per-session** (you), with the stricter session rules
checked first. Spend caps and access limits ship as builtins.

See the [policy guide](https://github.com/omnigent-ai/omnigent/blob/main/docs/POLICIES.md) for the full catalog and trust model.

---

## Write your own agent

For centrally managed remote tools, reusable account connections, and a gateway
with session policies around built-in or external backends, see the
[MCP registry and gateway prototype](examples/mcp-registry/README.md).
Direct MCP requests use the caller's connected account. A shared session's runner
uses its authenticated account (normally the owner), while policies evaluate the
turn's initiating user. Databricks connections ask for a workspace URL before
OAuth. KMS limits serialized grants to 4096 bytes; use Vault for larger grants.

An agent is a short YAML file: your prompt, your tools — local Python
functions, MCP servers, and sub-agents a supervisor can delegate to. You don't
have to write it by hand: agents can build agents, so describe the agent you
want in any Omnigent chat and it authors the file for you.

```yaml
name: my_agent
prompt: You are a helpful data analyst.

executor:
  harness: claude-sdk          # or: claude-native, codex, codex-native, cursor,
                               # cursor-native, hermes, hermes-native, opencode,
                               # pi, pi-native, openai-agents

tools:
  # A local Python function (schema auto-generated from the signature)
  word_count:
    type: function
    callable: mypackage.mymodule.word_count

  # Tools from an MCP server (a local command, or a remote URL)
  docs:
    type: mcp
    url: https://example.com/mcp

  # A sub-agent the supervisor can delegate to
  researcher:
    type: agent
    prompt: Search for relevant information and summarize it.
    tools:
      word_count: inherit
```

Run it with:

```bash
omnigent run path/to/my_agent.yaml
```

The same file can declare sub-agents and reviewers. For a fuller example, see
Polly at [`examples/polly/`](https://github.com/omnigent-ai/omnigent/tree/main/examples/polly/), and the
[Agent YAML spec](https://github.com/omnigent-ai/omnigent/blob/main/docs/AGENT_YAML_SPEC.md) for the full schema.

---

## Telemetry

Omnigent collects anonymized usage data (telemetry) by default. This data
contains no sensitive or personally identifiable information. If you're using
Omnigent through a managed service or distribution, please consult your managed
service agreement to determine any data collection that may impact your use of
the service. To opt out, follow our instructions in
[Usage Telemetry](https://omnigent.ai/docs/deploy/telemetry).

---

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](https://github.com/omnigent-ai/omnigent/blob/main/CONTRIBUTING.md) for how to set up your environment, run the checks, and open a pull request.

Adding or changing support for a harness (Claude, Codex, Cursor, OpenCode,
Hermes, Pi, ...)? Run the [harness test bench](https://github.com/omnigent-ai/omnigent/tree/main/tests/harness_bench)
to check its capability matrix against observed behavior.


### Contributors

Thanks to all of our amazing contributors!

<a href="https://github.com/omnigent-ai/omnigent/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=omnigent-ai/omnigent" />
</a>
