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:
- A
COPILOT_GITHUB_TOKEN,GH_TOKEN, orGITHUB_TOKENenvironment variable. - A token you stored through
omnigent setup→ configure harnesses → Copilot. - Your GitHub CLI login — if you've run
gh auth login, Omnigent asksghfor 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.comProvide 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
--permission-mode— one ofnormal(default),accept-edits,smart,dangerous, orbypass.--sandbox— enable Devin's OS-level process sandbox for itsexectool.-p,--prompt— send an initial chat input when the TUI starts.--resume [CONVERSATION]— resume a prior Omnigent conversation; with no value it opens a picker scoped todevin-nativesessions.
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).
- 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.jsonis still read. - Provider API-key variables — a common provider key such as
OPENAI_API_KEY,ANTHROPIC_API_KEY,XAI_API_KEY,MISTRAL_API_KEY, orDEEPSEEK_API_KEYset in the environment whereomnigent hostruns. - 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:
- Any of these AWS credential-chain variables is set (any non-empty value):
AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY,AWS_PROFILE,AWS_REGION,AWS_BEARER_TOKEN_BEDROCK,AWS_WEB_IDENTITY_TOKEN_FILE,AWS_CONTAINER_CREDENTIALS_FULL_URI, orAWS_CONTAINER_CREDENTIALS_RELATIVE_URI.omni setuplists this asenv: Amazon Bedrock. - Your OpenCode config (
~/.config/opencode/opencode.jsonor.jsonc) declares anamazon-bedrockprovider block, under either the 1.xproviderkey or the 2.xproviderskey. An empty{}is enough.omni setuplists this asconfig: amazon-bedrock.
{
"$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> # optionalWhen 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:
- Policy token snapshot. The policy plugin gets its Omnigent credentials when the server launches. If a session outlives that token, the request and tool-result policy phases fail open until the session is relaunched. Tool-call approvals are unaffected.
- No Direct mode. OpenCode runs only as a native TUI harness.
- Session import of your existing OpenCode sessions reads a snapshot copy of your OpenCode 2.x database, never the live store. A database last written by OpenCode 1.x must be opened once with OpenCode 2.0 to upgrade it before import works.
Troubleshooting
- Harness is outdated — install
@opencode/cli@2.0.32as shown above. - Auth-shaped turn error — the model's provider needs a sign-in. Run
opencode auth loginon the host, or pick a freeopencode/…model. - Diagnostics — set
OMNIGENT_HARNESS_STDERR_ENABLED=1before starting the host to copy OpenCode's server logs, redacted, into the runner log. Startup errors then quote the last lines. The per-conversation bridge directory holdsopencode.json, the policy plugin, and OpenCode's own log underxdg-data/opencode/log/.
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:
- 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). - The Antigravity API key saved by earlier versions of
omni setup. - A
GEMINI_API_KEYin the environment where the harness runs, paired withGOOGLE_GEMINI_BASE_URLwhen that is also set (otherwise Google's API root). Both variables are forwarded from the host to the runner. - Otherwise agy keeps its own Google OAuth login — run
agyonce and complete the browser sign-in. TheagyCLI has noagy login/agy auth statussubcommand: 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 have | Setup option | Requirements |
|---|---|---|
| Google Gemini API key | Gemini — API key | A key issued by Google AI Studio; setup supplies Google's API root. |
| External native Gemini gateway | Gemini API gateway — URL + key | Native Gemini generateContent / streamGenerateContent, x-goog-api-key authentication, and the models agy requests. |
| Databricks workspace | Databricks — profile | An 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 models | Not supported | Would need a protocol adapter, which Omnigent does not provide. Applies to Databricks and external gateways alike. |
| Gateway requiring Bearer auth or a token-refresh command | Not supported | agy 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:
- a path ending in
/v1beta,/openai,/responses,/chat/completions, or/completions, or containing a/models/segment; - an
openai.comhost; - a Databricks workspace host — use Databricks — profile instead;
- a URL with embedded credentials, a query string, or a fragment.
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:
| Gateway | API root to enter | Notes |
|---|---|---|
| LiteLLM Google AI Studio pass-through | http://127.0.0.1:4000/gemini for a local proxy | Gemini-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 integration | http://127.0.0.1:8080/genai for a local instance | Uses 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 route | https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/google-ai-studio | Provider-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:
- the
databricksextra in the environment running Omnigent (pip install 'omnigent[databricks]') — setup tells you if it's missing; - a local profile on the host — managed
connection: databricksproviders are not supported for native Gemini; - an HTTPS workspace root in the profile — HTTP hosts, including loopback, are rejected before authentication;
- access to the workspace's native Gemini API and the corresponding model
services. A workspace model page showing
/ai-gateway/mlflow/v1/responsesis an OpenAI Responses endpoint, even when its model is a Gemini service; availability there alone is insufficient.
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.
- 404 — check both the API route and the availability of the requested
model; changing
/modelcannot repair an incompatible API protocol. - 401 / 403 — check the key or profile login and model permissions.
Previously saved incompatible entries fail at launch with guidance instead of falling back to ambient credentials.
Upgrading from an earlier Omnigent
- A
gemini:block in an existingkind: gatewayorkind: localprovider becomes usable by native agy. If that provider hasdefault: true, Gemini is included in its defaults and takes precedence over agy OAuth; an incompatible URL then fails with a setup error rather than falling back. Update it to a native Gemini API root, or replacedefault: truewith an explicit list of its other families (for exampledefault: [anthropic, openai]) inconfig.yamlto restore OAuth for new sessions. You can also select another Gemini default in setup. - Setup does not automatically adopt a detected
GEMINI_API_KEYwhose companionGOOGLE_GEMINI_BASE_URLis incompatible. Correct the variable and reopen setup; if an earlier setup already saved the rejected URL, edit or remove that saved provider too — changing the environment alone does not replace it.
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.
- Your file is read again each time Omnigent writes a session's config, and
Omnigent never modifies it. Edits you make take effect on the next launch,
including
omni agy --resume. - On a name collision the relay wins: a server of your own named
omnigentis dropped from the session config. - If the file doesn't exist, the session gets only the relay. If it can't be
read, isn't valid JSON, or
mcpServersisn't an object, the session also gets only the relay, and Omnigent logs a warning that it is seeding only the Omnigent relay. - Server
envblocks are copied exactly as written, so the session copy can hold credentials. Omnigent writes it readable by its owner only (0600).
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:-}"
}
}
}
}- Name the entry
omnigent. Sessions call these toolsmcp__omnigent__<tool>, and Omnigent looks for this name to decide whether the entry is deployed. - Keep the
${...}references as written. Claude Code expands them from its own environment when it starts:
| Variable | Set by Omnigent to |
|---|---|
OMNIGENT_MCP_RELAY_PYTHON | The Python interpreter that runs Omnigent. |
OMNIGENT_MCP_RELAY_BRIDGE_DIR | The session's private relay directory, which also holds the relay's access token. |
OMNIGENT_MCP_RELAY_TMPDIR | The temporary directory Omnigent's relay directories live under. |
OMNIGENT_MCP_RELAY_SOCKET_DIR | Where 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. |
- An entry without the
OMNIGENT_HARNESS_TMP_PARENTline still works for unsandboxed sessions. Aclaude-sdksession in a macOS Seatbelt sandbox needs it: without it, the relay can't create its control socket and exits. - If managed settings define
allowedMcpServers, also list{"serverName": "omnigent"}there. Claude Code applies that allowlist to any managed entry that uses${VAR}, and silently drops the entry when it isn't listed. - Don't name
omnigentindeniedMcpServers. The denylist wins over the allowlist, and Claude Code drops a denied entry just as silently. Omnigent reads onlymanaged-mcp.json, not this policy, so with the entry denied or left off the allowlist, sessions start without Omnigent's tools and without the missing-entry warning.claude-sdktells the model that a missingmcp__omnigent__tool means the managed server didn't load, so the model reports that instead of retrying.
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:
- With the entry:
claude-sdksessions andclaude-nativesessions (both web-launched andomni claude) start with Omnigent's tools. - Without it: sessions still start, but without Omnigent's tools. The launching process logs: "Claude Code has an enterprise managed-mcp.json without Omnigent's relay entry; starting without Omnigent's MCP tools."
- Outside Omnigent: a plain
claudestarted by hand doesn't have these variables, soclaude mcp listreports theomnigententry as failed to connect. Nothing else is affected. - In a Linux bubblewrap sandbox: each
claude-sdkClaude Code process can read the managed config directory and use only its own session's relay directory. Other sessions' relay directories stay hidden. /mcp: while the file exists,/mcpin an Omnigent session lists only the servers inmanaged-mcp.json, because those are the only ones Claude Code loads. Theomnigententry itself is never listed.
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:
- A provider configured for the codex harness — the agent spec's
executor.authwhen you launch a custom agent, otherwise the provider you set up withomni setup(API key, gateway, or Databricks). - A provider Omnigent auto-detects on the machine when nothing has been configured yet.
- 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. - 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:
- A file profile at
~/.codex/<name>.config.tomlis layered when it exists — with or without a baseconfig.toml. - Otherwise the legacy inline
[profiles.<name>]table inconfig.tomlis used (Codex versions before 0.134 keep profiles inline).
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-proWith 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:
- Aliases. A tier value may name another tier — for example
default: deepseek-proalongsidedeepseek-pro: deepseek-v4-pro. Omnigent follows the alias to the concrete id, so the session launches withdeepseek-v4-proand the alias never appears as a picker row of its own. - Bracket suffixes. A
[...]suffix on a tier value (e.g.GLM-5.3[16m]) is stripped before the id reaches the gateway or the picker, matching how the launch model is handled.
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.
- Your Pi config wins. If an entry in
~/.pi/agent/mcp.jsonhas the same name and defines a transport (command,url, ortype), it replaces the host server. If it sets onlyenabled,exposure, ortoolExposure, it adjusts the host server instead. For example,{"name": {"enabled": false}}turns that server off for Pi. Pi treats-and_in server names as the same, sosearch-docsandsearch_docsclash. - Your agent dir is never written. When the host servers aren't already in
your file, the session's managed agent dir gets a merged copy of
mcp.json, readable only by its owner (0600). When your file already defines every host server, the session links your file directly. - Order on name clashes. When more than one harness defines the same name, Claude Code wins over Codex, and Codex wins over Cursor.
- Skipped servers. Omnigent leaves out (and logs) any server that Pi can't
load: SSE transports, names with characters other than letters, digits,
-, and_, Cursor substitutions other than${env:NAME}and${userHome}, and commands or URLs that reference an unset variable. - Variables. Claude Code and Cursor
${VAR}placeholders incommand,args, andurlresolve when the session launches. Placeholders inenvandheadersstay as variables that Pi reads when it starts the server, so the session's copy doesn't hold those secrets. A server that uses${VAR}in its env or headers connects only if the runner has that variable, for example throughOMNIGENT_RUNNER_ENV_PASSTHROUGH=VAR. Codex values are copied literally. Codexenv_http_headers,bearer_token_env_var,tool_timeout_sec, andenabled_tools/disabled_toolsare carried over.
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:
| Agent | Command |
|---|---|
| Gemini CLI | gemini --experimental-acp |
| Qwen Code | qwen --acp |
| Goose | goose 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-cliThe 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: falseNote: 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:
| Source | Path |
|---|---|
| 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: falseReplace <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/pidefault(optional) — the default harness id foromni run.command(optional) — overrides the vendor CLI executable for that harness.args(optional list) — base launch args; any CLI pass-through args are appended after these.
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:
- The
OMNIGENT_<NAME>_PATHenvironment variable. - The config
harness.<id>.command. - 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.