Configuration

Choose a harness id from Supported Harnesses, then configure any authentication or launch settings it needs.

GitHub Copilot

The copilot harness runs GitHub Copilot through the Copilot SDK (install the copilot extra). Launch it with the omni copilot shorthand, or spell out the harness on omni run:

omni copilot                         # shorthand for the line below
omni run --harness copilot

omni copilot forwards every omni run option unchanged, so flags like -p "review the last commit" or --model <id> work as they do on omni run. Because the shorthand always uses the Copilot harness, passing --harness to it is a usage error — use omni run --harness <name> to pick a different harness. Resume hints for a session started this way print the canonical omni run --harness copilot form. omni --help lists copilot under Harnesses only when the Copilot SDK is installed, the same way the cursor row follows its SDK extra.

Authentication

The copilot harness authenticates with a GitHub token that carries Copilot access. Omnigent resolves one from the first source that's set, in this order:

  1. A COPILOT_GITHUB_TOKEN, GH_TOKEN, or GITHUB_TOKEN environment variable.
  2. A token you stored through omnigent setup → configure harnesses → Copilot.
  3. Your GitHub CLI login — if you've run gh auth login, Omnigent asks gh for the token directly (gh auth token), so a logged-in user is ready without pasting anything into setup.

Note: The gh fallback runs gh auth token because the Copilot CLI only picks up a gh login by reading oauth_token from ~/.config/gh/hosts.yml — which is absent whenever gh keeps the token in an OS keychain (the default on macOS). Asking gh itself works on every platform.

GitHub Enterprise host

Organizations that reach Copilot through a GitHub Enterprise (data-residency) instance need auth and API calls pointed at their own hostname rather than github.com. Set it through omnigent setup → configure harnesses → Copilot → Set GitHub Enterprise host (the same menu lets you change or clear it), or edit ~/.omnigent/config.yaml directly:

copilot:
  github_host: acme.ghe.com

Provide a bare hostname; a pasted https:// scheme or trailing slash is stripped automatically. When set, Omnigent forwards it to the bundled Copilot CLI as the COPILOT_GH_HOST environment variable and fetches your gh token for that host. With no host configured, Copilot uses its default github.com.

Grok Build

Grok Build (xAI's grok CLI) ships as a builtin harness with the id grok (alias grok-build). Under the hood it drives grok agent stdio over the Agent Client Protocol — Omnigent renders its streaming output, reasoning, and tool cards and routes its permission requests through your contextual policies, just like the generic acp harness below. The difference is that it's built in: you select the grok harness id directly instead of registering a launch command.

omni run --harness grok

Like the generic ACP agents, Grok Build brings its own auth and model — Omnigent stores no credential and a /model pick is rejected up front (rather than silently dropped), so it always runs its account-default model. To pin one, configure an acp: agent whose command passes the grok CLI's own model flag. Install the CLI and log in through xAI first:

curl -fsSL https://x.ai/cli/install.sh | bash
grok login --device-auth   # xAI OAuth (device-code capable)

Use the vendor login rather than an API key. The builtin grok 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.

Devin

Devin (Cognition) ships as a built-in native TUI harness with the id devin-native. omni devin boots the resident Devin CLI in a runner-owned pane and mirrors it into an Omnigent conversation, so you get contextual policies, approval cards, resume, cost tracking, and Devin's sub-agents as child sessions on top of the native experience.

curl -fsSL https://cli.devin.ai/install.sh | bash
devin auth login
omni devin

Devin brings its own auth — Omnigent stores no credential. The CLI writes its own credential file and reads it back at launch, and devin auth status is a live probe, so omni setup reports the real sign-in state.

Approvals surface two ways: Omnigent policies gate each request, tool call, and tool result, and Devin's own consent prompt is republished as a Chat approval card (answerable in the web UI or the embedded terminal).

When Devin asks you a question with its ask_user_question tool, Omnigent shows the question form in Chat and Inbox under Devin needs your input, even in bypass permission mode. Pick an option (or several, when the question allows multiple selections), or type a custom answer, and Omnigent passes the answer back to the running tool. A pending question is still there after a page reload. Your contextual policies run first, so a policy denial blocks the question. If Omnigent can't deliver the form or the request times out, Devin opens its own picker in the terminal instead. Dismissing the form cancels the question.

Model and effort

Devin encodes reasoning effort as a suffix on the model id. Omnigent keeps model and effort as separate axes and recombines them at launch. Pass a model family slug or alias from devin models list, and optionally an effort rung:

omni devin --model opus --effort xhigh
omni devin --model gemini --effort max

--effort accepts low, medium, high, xhigh, or max; a family with no matching rung falls back to its default variant, so a mismatched pair costs effort, not the session. You can also switch models mid-session with /model.

Launch options

Devin's own --resume/-c/--config/--export flags are reserved for Omnigent, which owns resume and hook wiring; use omni devin --resume instead.

The devin and native-devin spellings both resolve to devin-native. The former built-in ACP row devin-acp was removed in 0.14 and its id now aliases onto the native wrap, so existing sessions and scripts keep resolving. A user-configured acp: agent for Devin is unaffected.

Jcode

Jcode (jcode.sh) ships as a builtin harness with the id jcode. Like Grok Build, it drives its vendor CLI (jcode acp) over the Agent Client Protocol over stdio — Omnigent renders its streaming output, reasoning, and tool cards and routes its permission requests through your contextual policies. It's built in, so you select the jcode harness id directly instead of registering a launch command.

omni run --harness jcode

Jcode brings its own auth and model — Omnigent stores no credential. Jcode ships via a curl installer (no npm package) and owns its provider and model selection in ~/.jcode/config.toml, so install the CLI and configure a provider there first:

curl -fsSL https://jcode.sh/install | bash

Note: Unlike most builtin ACP harnesses, Jcode's ACP server does not support session-scoped MCP — it ignores the mcpServers sent in session/new. Omnigent therefore does not advertise its builtin MCP tools (session, sub-agent, skill, and policy tools) to Jcode. Configure any MCP servers Jcode should use in its own ~/.jcode/mcp.json instead.

Hermes

Hermes ships as a builtin harness with the id hermes and is offered directly in the web harness picker. Select it like any other builtin — in the picker, via --harness hermes, or in agent YAML:

executor:
  harness: hermes
  model: hermes-4-405b

Like the ACP agents, Hermes brings its own auth — Omnigent stores no credential and injects none. Hermes reads credentials from its own file-based store (auth.json / .env under HERMES_HOME), so log in and pick a model through its own CLI first:

hermes setup    # file-based auth under HERMES_HOME
hermes model    # choose the model Hermes runs

Unlike the generic ACP agents, a /model pick is honored for Hermes: the model you declare in YAML or switch to mid-session threads through to the harness (via HARNESS_HERMES_MODEL). The sandbox and workspace a session selects are threaded through as well, so a sandbox chosen in the web session dialog actually confines the Hermes run.

Kimi Code

Kimi Code (kimi, alias kimi-code) brings its own auth — Omnigent stores no credential. Kimi ships via a curl installer (no npm package), so install the CLI and sign in through it first:

curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
kimi login   # Moonshot OAuth, or paste a Moonshot API key

kimi login writes its credential to ~/.kimi-code/credentials/kimi-code.json. omni setup detects that file and shows Kimi as Signed in once a login has completed; while the CLI is installed but no credential is present it shows Not configured with a "Sign in with kimi login" hint.

Kimi has no kimi logout subcommand, so omni setup offers no sign-out row. To sign out, delete the credential file:

rm ~/.kimi-code/credentials/kimi-code.json

OpenCode

The native OpenCode harness (opencode-native, aliases opencode and native-opencode) runs the real OpenCode TUI in a runner-owned tmux pane and mirrors it into the Omnigent conversation. Launch it with omni opencode.

Supported version

The harness requires OpenCode 2.0.18 or a later 2.0.x patch (>=2.0.18,<2.1.0), published on npm as @opencode/cli. Newer minors are refused until they are validated, and OpenCode 1.x (the opencode-ai package) is no longer supported. A host with an unsupported version reports the harness as outdated until you upgrade it. Set OMNIGENT_OPENCODE_SKIP_VERSION_CHECK=1 to bypass the version gate at your own risk.

npm rm -g opencode-ai            # only if OpenCode 1.x is installed
npm i -g @opencode/cli@2.0.32
opencode auth login              # optional; free models need no sign-in
omni opencode

omni setup → OpenCode runs the same install and offers the optional login. The web UI's setup dialog shows the same checklist for a remote host. Both OpenCode packages install the same global opencode binary, and Omnigent never removes packages. If opencode-ai is still installed, setup stops and asks you to run npm rm -g opencode-ai yourself.

Authentication

No sign-in is required. Once OpenCode is installed the harness is ready, with OpenCode's built-in free models such as opencode/big-pickle. Sign in to a provider only to use your own models. Omnigent stores no OpenCode credential. omni setup reads these sources, without touching the secrets, to report which providers OpenCode can reach. With none of them it reports free models only (no provider signed in).

  1. Stored login — run opencode auth login. OpenCode 2.x keeps the credential in its database (~/.local/share/opencode/opencode.db). A legacy ~/.local/share/opencode/auth.json is still read.
  2. Provider API-key variables — a common provider key such as OPENAI_API_KEY, ANTHROPIC_API_KEY, XAI_API_KEY, MISTRAL_API_KEY, or DEEPSEEK_API_KEY set in the environment where omnigent host runs.
  3. Amazon Bedrock — see below.

At launch, the runner writes a per-conversation auth.json that merges your legacy auth.json with your OpenCode 2.x credential store (the store wins on conflicts). OpenCode imports it once into the conversation's private database. Provider keys that exist only in the runner's environment are then connected through OpenCode's integration API.

Amazon Bedrock

Bedrock is the exception to the API-key pattern: OpenCode loads it from the AWS credential chain and the AWS SDK authenticates at run time, so there is no stored credential or provider key to detect. omni setup reports Bedrock as reachable when either of the following holds:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": { "options": { "profile": "work" } }
  },
  "model": "amazon-bedrock/anthropic.claude-sonnet-4-5-20250929-v1:0"
}

Two things do not count on their own: an enabled_providers list naming amazon-bedrock (it only filters which providers OpenCode shows), and AWS variables OpenCode's Bedrock loader ignores — AWS_SESSION_TOKEN, AWS_DEFAULT_REGION, and AWS_SHARED_CREDENTIALS_FILE. A malformed config file credits nothing.

Note: The Bedrock check only looks for a declaration and never contacts AWS. Setup can list Bedrock with a profile or key that AWS later rejects. The failure appears when OpenCode makes its first model call.

Model and instructions

A model id uses OpenCode's provider/model form, for example anthropic/<model-id>:

executor:
  type: omnigent
  config:
    harness: opencode-native
    model: anthropic/<model-id>   # optional

When the agent is bound to the Omnigent or Databricks gateway, give a bare endpoint name and Omnigent qualifies it as <gateway-provider>/<endpoint>. omni opencode --model and omni setup → OpenCode → Set default model (opencode_model) set the same value. /model <id> in the web composer switches the running session.

The agent's prompt / instructions and Omnigent's framework instructions are written to the conversation's private AGENTS.md once per launch, after your own global ~/.config/opencode/AGENTS.md if you have one. OpenCode 2.x reads that file, not the config's instructions key.

Approvals and policies

Every OpenCode tool call asks for approval first. The runner writes an ask-all permissions rule ({action: "*", resource: "*", effect: "ask"}) into the per-conversation config and never passes --auto, so every call goes through the Omnigent policy engine. An ASK verdict becomes a web approval card. The first answer wins, whether it comes from the web card or the TUI. OpenCode question forms appear as web question cards.

Omnigent's relay tools, and any MCP servers merged from your own OpenCode config, run with OpenCode's Code Mode off. Each MCP call is asked under its own <server>_<tool> name, so a policy can gate it by name. OpenCode's permission.asked actions shell, edit, read, grep, and glob count as OS tools for ask_on_os_tools. So do OpenCode's MCP resource builtins (opencode_list_mcp_resources, opencode_read_mcp_resource): they can reach any configured server and have no config switch to turn them off. block_skills also applies to OpenCode's skill action.

Images attached in the web UI are sent to OpenCode, and other attachments are flattened to text. A message sent during a running turn is delivered as a steer, and queued messages use OpenCode's own queue.

One server per conversation

Each conversation gets its own opencode serve process, password, and data directory (with its own opencode.db) under $OMNIGENT_DATA_DIR/opencode-native/ (default ~/.omnigent/opencode-native/). Resume reattaches to the same data directory on the same host. Resuming on a different host, or resuming a lost session, starts a new OpenCode session seeded with the Omnigent transcript. A same-agent fork into the same workspace clones the OpenCode session natively. Any other fork replays the history as a text preamble.

Known limits:

Troubleshooting

Antigravity

The native Antigravity harness (antigravity-native, launched by omni agy) wraps Google's agy CLI. It requires agy 1.1.13 or newer. Install the CLI first:

curl -fsSL https://antigravity.google/cli/install.sh | bash

agy speaks the native Gemini API (generateContent / streamGenerateContent, authenticated with an x-goog-api-key header). For each session Omnigent resolves the API key and endpoint together, from the first source that applies:

  1. The Gemini default provider you configured through omni setup — a Google API key, a native Gemini gateway, or a Databricks profile (see Configure native agy credentials).
  2. The Antigravity API key saved by earlier versions of omni setup.
  3. A GEMINI_API_KEY in the environment where the harness runs, paired with GOOGLE_GEMINI_BASE_URL when that is also set (otherwise Google's API root). Both variables are forwarded from the host to the runner.
  4. Otherwise agy keeps its own Google OAuth login — run agy once and complete the browser sign-in. The agy CLI has no agy login / agy auth status subcommand: the token is written on its first interactive run. Omnigent recognizes it at ~/.gemini/oauth_creds.json (macOS), ~/.gemini/antigravity-cli/antigravity-oauth-token (Linux), or the macOS Keychain (agy 1.1.7+).

Whenever an API key is resolved, Omnigent selects agy's direct Gemini provider (modelProvider: "gemini" in the session's isolated agy settings) and the key takes precedence over any saved OAuth login. A configured provider that cannot be resolved — an empty key or an incompatible URL — fails the session start with a setup error pointing at omni setup, rather than silently falling back to OAuth or ambient credentials.

omni setup shows the harness as ready once the agy binary is present and a credential resolves (or an OAuth login is detected). The Antigravity row names the active credential, or reads Credential needs setup when the selected provider can't be resolved.

Configure native agy credentials

Run omni setup → Antigravity → Configure native agy API key / gateway → Add a credential, then pick the option matching what you have:

What you haveSetup optionRequirements
Google Gemini API keyGemini — API keyA key issued by Google AI Studio; setup supplies Google's API root.
External native Gemini gatewayGemini API gateway — URL + keyNative Gemini generateContent / streamGenerateContent, x-goog-api-key authentication, and the models agy requests.
Databricks workspaceDatabricks — profileAn authenticated Databricks CLI profile, the databricks extra, and access to the workspace's native Gemini API and model services.
OpenAI Responses or Chat Completions endpoint — even one serving Gemini modelsNot supportedWould need a protocol adapter, which Omnigent does not provide. Applies to Databricks and external gateways alike.
Gateway requiring Bearer auth or a token-refresh commandNot supportedagy sends a static x-goog-api-key; a gemini: provider family may not set auth_command.

The first credential you add becomes the Gemini default; adding another keeps the existing default. To switch, select the credential, choose Make default for Gemini, and start a new omni agy session — existing sessions keep their original connection, and /model changes the model, not the provider, endpoint, or authentication method. Claude, Codex, and Pi defaults are separate.

Note: These settings configure native agy only. The in-process antigravity SDK harness is a separate integration that keeps its own API-key / Vertex AI setup.

External Gemini API gateway

Setup first asks for a gateway label (a name you choose, e.g. team-gemini), then the gateway's native Gemini API root, the key its Gemini route accepts (a gateway virtual key, or a Google key for provider-key pass-through), and optionally an agy model (a --model value; leave it blank for agy's default).

Enter the API root only, for example https://gateway.example/gemini. agy appends the operation itself, sending requests to https://gateway.example/gemini/v1beta/models/<model>:streamGenerateContent. Setup rejects recognizable mistakes before asking for a key:

http:// roots are accepted (useful for a local proxy), and the URL must be reachable from the machine running agy — localhost refers to that machine, including when it is a remote host. The key is stored in Omnigent's secret store and referenced from the provider entry.

The gateway must preserve Gemini request and response fields, streaming events, tool calls, tool results, and reasoning metadata such as thought signatures, and it must serve the auxiliary Gemini models agy requests — setting the main model does not redirect every auxiliary request to it. Setup validates the URL shape only; it does not send an inference request, so a saved credential or a green setup row is not proof the full agent flow works. This option does not refresh expiring upstream tokens. Use the smoke steps below.

The following gateways document native Gemini frontends. They are documented candidates, not gateways live-verified with agy:

GatewayAPI root to enterNotes
LiteLLM Google AI Studio pass-throughhttp://127.0.0.1:4000/gemini for a local proxyGemini-native requests and streaming without protocol translation. Configure the Google key on the proxy and use a LiteLLM key in Omnigent; allow every main and auxiliary model agy requests.
Bifrost GenAI integrationhttp://127.0.0.1:8080/genai for a local instanceUses a Bifrost virtual key. This frontend adapts requests and responses, so verify tool and reasoning metadata through the full agent flow.
Cloudflare AI Gateway Google AI Studio routehttps://gateway.ai.cloudflare.com/v1/<account>/<gateway>/google-ai-studioProvider-key pass-through uses a Google key. Configurations that require the extra cf-aig-authorization header need more header support than the URL-and-key form provides.

OpenAI-compatible routes from the same products are not interchangeable with these native Gemini routes.

Databricks

Choose Databricks — profile and enter an existing profile name from ~/.databrickscfg (or the file selected by DATABRICKS_CONFIG_FILE), for example work. Do not paste a workspace URL or token into the gateway option — setup rejects Databricks hosts there. This path requires:

For a CLI OAuth login, sign in and then run setup:

databricks auth login --profile work
omni setup

PAT and service-principal credentials belong in the profile configuration and need no interactive login. Setup authenticates the profile before saving it and stores the provider as databricks-gemini-<profile> with native_gemini: true in ~/.omnigent/config.yaml; that flag scopes the entry to the Gemini surface only (a regular Databricks profile keeps serving Claude, Codex, and Pi).

At launch Omnigent starts a local adapter alongside each agy process. It supplies the profile's Bearer token, refreshes access tokens through the profile's authentication provider, maps agy's model names onto the workspace's Gemini model services, and forwards native Gemini bodies and streaming responses unchanged to:

https://<workspace>/ai-gateway/gemini/v1beta/models/<model-service>:streamGenerateContent

The adapter requires the same main and auxiliary model versions agy requests; an unavailable or ambiguous match fails rather than substituting a different version. It stops with agy and is recreated on resume — you never manage its local URL or session key. The selected profile owns both the workspace and the identity: ambient DATABRICKS_HOST, DATABRICKS_TOKEN, and OAuth client settings cannot override it, and an invalid profile fails instead of using ambient credentials.

If OAuth refresh fails, run databricks auth login --profile work again in the same environment. Omnigent does not require DATABRICKS_AUTH_STORAGE=plaintext (some CLI versions use it for an older file credential cache); use a consistent storage setting for login and Omnigent, and restart an existing local host daemon after changing its authentication environment.

Verify the connection

Create a small file in your working directory and start a session:

printf 'Gateway smoke: file tools work.\n' > gateway-smoke.txt
omni agy

Ask: Read gateway-smoke.txt using the file tool and quote its contents. Confirm a tool call occurs and the reply contains the file's actual text, then ask a follow-up question about it. Exit and run omni agy --resume to verify continuity. Repeat in a fresh conversation after switching credentials.

Previously saved incompatible entries fail at launch with guidance instead of falling back to ambient credentials.

Upgrading from an earlier Omnigent

MCP servers

Each agy session (omni agy and web-started sessions) runs with its own isolated agy Gemini directory, so Omnigent never writes to your real ~/.gemini. That directory gets a session-scoped config/mcp_config.json containing the Omnigent MCP relay (the omnigent server) plus every server in the mcpServers object of your own ~/.gemini/config/mcp_config.json. MCP servers you've already configured for agy are available inside Omnigent sessions without extra setup.

Permission prompts

Antigravity permission prompts appear in Chat and Inbox. You can approve or reject commands and use agy's pattern-based always-allow choices when available. Rules saved through these prompts apply only to the current Omnigent session.

Claude Code

Enterprise managed-mcp.json

An organization can pin Claude Code's MCP servers with an enterprise managed-mcp.json (/Library/Application Support/ClaudeCode/managed-mcp.json on macOS, /etc/claude-code/managed-mcp.json on Linux). While that file exists, Claude Code loads only the servers it lists. It ignores user, project, and plugin servers, and it refuses --mcp-config, which is how Omnigent normally hands each claude-sdk and claude-native session its own tools (sys_session_*, sys_os_*, skills, and the rest).

To keep those tools, add one static omnigent entry to the file. Omnigent sets the variables it reads for each session, so the same entry serves every session and every user on the machine. Merge it into the file's mcpServers and keep the organization's other servers:

{
  "mcpServers": {
    "omnigent": {
      "command": "${OMNIGENT_MCP_RELAY_PYTHON}",
      "args": [
        "-I",
        "-m",
        "omnigent.harnesses.claude_native.bridge",
        "serve-mcp",
        "--bridge-dir",
        "${OMNIGENT_MCP_RELAY_BRIDGE_DIR}"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "TMPDIR": "${OMNIGENT_MCP_RELAY_TMPDIR}",
        "OMNIGENT_HARNESS_TMP_PARENT": "${OMNIGENT_MCP_RELAY_SOCKET_DIR:-}"
      }
    }
  }
}
VariableSet by Omnigent to
OMNIGENT_MCP_RELAY_PYTHONThe Python interpreter that runs Omnigent.
OMNIGENT_MCP_RELAY_BRIDGE_DIRThe session's private relay directory, which also holds the relay's access token.
OMNIGENT_MCP_RELAY_TMPDIRThe temporary directory Omnigent's relay directories live under.
OMNIGENT_MCP_RELAY_SOCKET_DIRWhere the relay's control socket goes. claude-sdk sessions get a private directory, so a sandbox can grant it without sharing the socket root. claude-native sessions get the configured harness socket root (OMNIGENT_HARNESS_TMP_PARENT). Empty means the default root.

Security note. This entry hands its executable (${OMNIGENT_MCP_RELAY_PYTHON}) and its tool surface (the bridge directory) to whatever environment launches Claude Code. A Claude started separately can set these variables and run another program under the approved omnigent name. An organization that needs an administrator-fixed tool catalog shouldn't deploy this entry.

What to expect:

Through this entry, each Omnigent tool call runs in the relay with a budget of 300 seconds of active work; time spent waiting for an approval doesn't count. When a call runs past it, Omnigent asks the tool to stop and returns an error: "Omnigent tool dispatch timed out after 300s of active work (approval waiting excluded). Cancellation requested; completion is unknown." The work may have partly finished, so check its effects before retrying. The budget applies even to a tool given a longer timeout of its own, such as a sys_os_shell command, and no setting changes it. Claude Code's own MCP tool timeout (MCP_TOOL_TIMEOUT, or a per-server timeout) also applies, so whichever is shorter ends the call. Without a managed file, claude-sdk runs Omnigent's tools in-process, where this relay budget doesn't apply.

Codex

The native Codex harness (codex-native, launched by omni codex) decides how a session authenticates before it starts the Codex CLI. In roughly this order, the first source that applies wins:

  1. A provider configured for the codex harness — the agent spec's executor.auth when you launch a custom agent, otherwise the provider you set up with omni setup (API key, gateway, or Databricks).
  2. A provider Omnigent auto-detects on the machine when nothing has been configured yet.
  3. A self-sufficient built-in Codex provider selected by your own Codex config.toml (~/.codex/config.toml). Codex authenticates these providers itself, so no Omnigent provider and no Codex login is needed.
  4. The Codex CLI's own login (codex login).

Use your Codex config.toml provider

If plain codex already runs on your machine because ~/.codex/config.toml selects a built-in provider that brings its own credentials, omni codex routes the same way instead of failing the first turn with "Codex is not signed in and no Omnigent provider routes the codex harness". Every built-in Codex provider except openai qualifies — Amazon Bedrock (amazon-bedrock, amazon-bedrock-runtime), Ollama (ollama), and LM Studio (lmstudio). An explicit model_provider = "openai" still defers to Codex's own login.

# ~/.codex/config.toml
model = "openai.gpt-5.6-terra"
model_provider = "amazon-bedrock"
 
[model_providers.amazon-bedrock.aws]
region = "us-east-1"

With this file and no Omnigent provider configured, omni codex launches with model_provider="amazon-bedrock" and Codex resolves the AWS credential chain itself. The session's provider summary names the built-in provider so you can see which route was taken. A provider configured through omni setup (tier 1 above) still takes precedence over the ambient config.toml selection.

Omnigent also leaves built-in provider tables such as [model_providers.amazon-bedrock] untouched when it writes the session's private config.toml; only custom [model_providers.<name>] tables receive Omnigent's retry settings (request_max_retries and friends), because Codex discards the whole config when a built-in table carries fields it doesn't recognize.

Select a Codex profile with --profile

The ambient config is read through the --profile (or -p) you pass to Codex, whether as a CLI pass-through arg or via harness.codex-native.args. Omnigent layers the selected profile over ~/.codex/config.toml exactly the way Codex does at start:

So omni codex --profile bedrock routes through Bedrock when that profile sets model_provider = "amazon-bedrock", even if the base config doesn't, and --profile openai over a Bedrock base keeps Codex's own login. A profile that exists nowhere leaves this tier alone (the launch falls through to Codex login), and a malformed selector — a missing value, a repeated --profile, or an invalid profile name — is reported by launch-arg validation when the session starts rather than during routing.

Pi

The native Pi harness (pi, alias pi-native) runs the Pi CLI against the provider you configured with omni setup, writing a managed models.json and per-session Pi settings so Pi authenticates with the provider's key rather than its own credential env vars.

Curated /model shortlist

A gateway provider family can declare a models: map of named tiers. When that map contains more than one distinct model id, Omnigent registers every tier with Pi and scopes Pi's /model picker to exactly that set, listed under the omnigent provider:

# ~/.omnigent/config.yaml
providers:
  bifrost:
    kind: gateway
    default: true
    openai:
      base_url: http://bifrost.example.com/v1
      api_key: <your-gateway-key>
      wire_api: chat
      models:
        default: GLM-5.3-Flash
        opus: GLM-5.3
        pro: deepseek-v4-pro

With this config, /model in a Pi session shows GLM-5.3-Flash, GLM-5.3, and deepseek-v4-pro (each once — tiers that resolve to the same id collapse into a single row) and hides Pi's built-in provider catalogs. The scope is a picker preference written to the session's managed Pi settings as enabledModels, so you can still toggle the picker back to all models from inside Pi.

Two details about how tier values are resolved:

The shortlist only comes from a configured models: map. A family with no map, a map that resolves to a single id, or a --model override on a default-only setup does not scope the picker, and a catalog discovered live from the endpoint never does — in those cases any enabledModels preference you already keep in your own Pi settings is left as-is.

Keep other harnesses' credentials out of Pi

Pi activates a built-in provider's whole catalog when it merely sees that provider's credential variable in its environment — whatever the value. A deployment that exports a placeholder token for another harness (for example ANTHROPIC_AUTH_TOKEN so claude-code can talk to a gateway) would therefore see Pi's picker flooded with built-in entries that bypass the managed provider.

Pi's own auth rides the managed models.json key and needs none of those variables, so you can name the ones to strip from the Pi terminal's environment with OMNIGENT_PI_ENV_UNSET, a comma-separated list of variable names:

OMNIGENT_PI_ENV_UNSET=ANTHROPIC_AUTH_TOKEN,OPENAI_API_KEY

Names are trimmed and de-duplicated; when the variable is unset or blank, nothing is stripped. Set it in the environment where omnigent host runs — the variable carries names only, so it is forwarded through both the host daemon and the spawned runner without forwarding the named secrets themselves, and the Pi terminal removes those variables before launching pi. Other harnesses in the same deployment are unaffected.

MCP servers from Claude Code, Codex, and Cursor

Pi sessions that Omnigent manages (omnigent pi with an Omnigent provider, and the Pi gateway executor) also get the MCP servers you've configured for Claude Code (~/.claude.json), Codex (config.toml), and Cursor (~/.cursor/mcp.json). You don't need to repeat them in Pi's own ~/.pi/agent/mcp.json; run /mcp in the session to see them listed and connected. Pi's built-in MCP support requires Pi 0.99 or newer.

Custom ACP agents

Beyond the built-in harnesses, the generic acp harness drives any agent that speaks the Agent Client Protocol — the open, editor-agnostic protocol used by Gemini CLI, Qwen Code, Goose, and in-house agents. You point Omnigent at a launch command and it speaks ACP against whatever that command starts.

Each ACP agent brings its own auth — Omnigent stores no credential, so log into the agent through its own CLI first. Register agents with omnigent setup → configure harnesses → Custom ACP agent → Add, providing a name, a launch command, and an optional model. (To pull agents in from an existing OpenClaw/acpx registry instead of typing each one, see Import agents from OpenClaw below.) Some paste-ready commands:

AgentCommand
Gemini CLIgemini --experimental-acp
Qwen Codeqwen --acp
Goosegoose acp

Each registered agent is stored in a top-level acp: block of ~/.omnigent/config.yaml and gets a stable slug derived from its name. It then surfaces as its own harness id, acp:<slug>, in the web picker and in agent YAML:

acp:
  agents:
    - { name: Gemini CLI, command: gemini --experimental-acp }
    - { name: Goose, command: goose acp, model: gpt-5.3 }
executor:
  harness: acp:gemini-cli

The agent runs its own agent loop, tools, and context window; Omnigent renders its streaming output, reasoning, and tool cards, routes its permission requests through your contextual policies as web elicitation cards, and honors interrupts. Omnigent also exposes its own builtin tools (session, sub-agent, skill, and policy tools) to the agent alongside the agent's native tools; set OMNIGENT_ACP_MCP=0 to disable that bridge for a session.

To disable that MCP relay permanently for a specific agent, set omnigent_mcp: false on its acp: entry. The agent keeps its own native tools; Omnigent simply stops lending its builtin tools to that agent in session/new (the field is still sent as an empty list, which ACP requires). This is required for agents whose ACP server rejects per-session MCP servers — such as the OpenClaw Gateway bridge described below. The value must be a boolean; omnigent setup reports an error if it isn't.

acp:
  agents:
    - name: OpenClaw
      command: openclaw acp --url <gateway-url> --token-file <token-file>
      omnigent_mcp: false

Note: The generic ACP harness has no fixed binary — each agent owns its own install and login, so a missing binary is a hint, not a hard gate. A sandboxed generic ACP agent gets read access to its binary directory, the cwd, and write access to /tmp; an agent that must write its own config directory needs sandbox: none (the default) for now.

Import agents from OpenClaw

If you already keep an agent registry for OpenClaw or the acpx CLI, Omnigent can import those agents into its acp: block instead of re-adding each one by hand. Run omnigent setup → configure harnesses → Import from OpenClaw. The row shows how many agents were detected automatically. Omnigent looks in two default locations:

SourcePath
acpx~/.acpx/config.json
OpenClaw~/.openclaw/openclaw.json

Both files are read as JSON5, and you can pick Choose another file… to point at a config elsewhere. Omnigent lists the agents it found, derives a stable slug from each name, and — after you confirm — appends them to the acp: block of ~/.omnigent/config.yaml. From then on they behave exactly like manually added ACP agents.

Import stores only the launch command, not credentials — each agent still authenticates through its own CLI. Re-running the import is safe: agents already present are skipped, and a new agent whose name collides with an existing slug gets a numbered suffix (e.g. gemini-cli-2) so nothing is overwritten. An agent whose binary isn't on your PATH is flagged as a hint, not blocked.

To launch a single OpenClaw/acpx agent once without saving it to your config, use --from-openclaw on omni run:

omni run --from-openclaw "Gemini CLI" -p "review the last commit"

Match the agent by its display name (case-insensitive) or derived slug. This runs the agent through the acp harness for that one session; it can't be combined with an AGENT path or with --harness.

This path drives the selected coding agent directly. It does not bring OpenClaw's Gateway session, routing, memory, or channels into the conversation — for that, register the Gateway bridge (below).

Drive the OpenClaw Gateway

Beyond importing individual coding agents, the openclaw acp command exposes a live OpenClaw Gateway session as an ACP server over stdio, giving Omnigent access to OpenClaw's own routing, memory, and channels. Register it as an acp: agent, disabling Omnigent's MCP relay because the Gateway bridge rejects per-session MCP servers:

acp:
  agents:
    - name: OpenClaw
      command: openclaw acp --url <gateway-url> --token-file <token-file>
      omnigent_mcp: false

Replace <gateway-url> and <token-file> with your running Gateway's connection details, then launch it:

omni run --harness acp:openclaw

Caution: Prefer --token-file so the Gateway token isn't stored in the launch command. Don't commit or share ~/.omnigent/config.yaml, and use a token with the narrowest permissions OpenClaw supports.

Omnigent owns the outer conversation and transcript; OpenClaw owns the Gateway-backed session. OpenClaw's Control UI is a separate Gateway client, so messages entered there while Omnigent is offline are not imported into the Omnigent conversation — use Omnigent as the canonical conversation when you need its transcript and resume behavior. Bidirectional sync with the Control UI and per-session Omnigent MCP are not supported by this integration.

Swap harnesses

Tools, policies, and other config stay the same across harnesses. Just change the harness value in your YAML, or override it at runtime:

omni run agent.yaml --harness codex

See Models & Credentials for how to set up API keys and choose models.

Override the harness binary and launch args

By default each harness launches its vendor CLI from your PATH (e.g. claude, codex). You can point a harness at a specific executable, or prepend base launch args, from your user-level Omnigent config, ~/.omnigent/config.yaml. A project's .omnigent/config.yaml can select the default harness but cannot set per-harness commands or args. View the config with omni config list; set a value with omni config set --global <key>=<value>.

The top-level harness: config key is polymorphic. The legacy scalar form still works (and auto-migrates to the mapping form the next time the config is written):

# Legacy scalar (deprecated, still honored):
harness: claude-sdk
 
# Mapping form — a default plus per-harness startup overrides:
harness:
  default: claude-sdk
  codex-native:
    command: /usr/local/bin/codex
    args: [--config, approval_policy=on-request]
  pi-native:
    command: /opt/bin/pi

This top-level harness: config key selects the CLI default and per-binary launch overrides. It's separate from the executor.harness value inside an agent's own YAML, which pins the harness for that one agent.

Note: Harness executables and launch args are user-owned. In a project's .omnigent/config.yaml, only the harness selection is honored, either as the scalar form (harness: codex-native) or as harness.default. Your user-level per-harness command/args entries still apply. Any per-harness entries in the project file (for example harness.codex-native) are ignored with a warning, and omni config list lists them as # ignored project harness launch overrides: ... and tells you to move them to ~/.omnigent/config.yaml.

Binary-path precedence

For a harness's command, the first non-empty source wins:

  1. The OMNIGENT_<NAME>_PATH environment variable.
  2. The config harness.<id>.command.
  3. The harness's built-in default executable.

args follow the same idea: the config args are the base, and CLI pass-through args are appended after them.

<NAME> is the harness's underlying binary, not its id: the -native suffix is stripped, so pi and pi-native share OMNIGENT_PI_PATH, and the Claude harnesses map to OMNIGENT_CLAUDE_PATH (so claude-sdk and claude-native share one var).

Deprecated: The older HARNESS_<NAME>_PATH env vars (for codex, pi, kimi, goose, qwen, and hermes) are still read as a fallback but log a warning and will be removed in v0.8.0 — use OMNIGENT_<NAME>_PATH instead. The omni claude --command flag is likewise deprecated (set OMNIGENT_CLAUDE_PATH or harness.claude-native.command instead) and will be removed in a future release. No other native command has a --command flag.

To add a runtime that Omnigent does not include, see Community Harnesses.