Unity Gateway runs coding agents through your Databricks workspace. It configures Codex, Claude Code, Gemini CLI, OpenCode, Kilo, GitHub Copilot CLI, Pi, and Google Antigravity CLI, and can register Databricks MCP servers for Cursor Agent.
The command is ug. Existing ucode commands remain supported, and the Python
package is still named ucode for compatibility.
- Python 3.12+
uvnpm, when an agent CLI needs automatic installation
uv tool install git+https://github.com/databricks/unity-gateway
ug --version
ug --help--version reports installed package metadata without loading the CLI. Use
ug --help (or ucode --help) to verify that the CLI's startup imports work;
version output alone is not an installation health check. Help does not validate
workspace authentication or agent runtime behavior.
Reinstall under the new distribution name:
uv tool uninstall ucode
uv tool install git+https://github.com/databricks/unity-gateway
ug --version
ucode --version
ug --help
ucode --helpFuture upgrades can use ug upgrade or uv tool upgrade unity-gateway.
Run the tool you want:
ug codex
ug claude
ug gemini
ug opencode
ug kilo
ug copilot
ug pi
ug antigravity # Google Antigravity CLI; `ug agy` is an alias
ug cursor # Cursor Agent, MCP-onlyOn first launch of a model-backed agent, ug prompts for a Databricks
workspace, authenticates, and writes local agent config. Later launches reuse
the saved workspace and credentials.
When Claude Code or Codex is older than the minimum version ug supports, ug
asks before upgrading it in place. Set UG_AUTO_UPGRADE_AGENT=1 to upgrade
without asking, for example from a launcher that manages the agent install.
Codex smart routing now requires 0.164.0, including existing managed-enabled
workspaces. See the compatibility and upgrade note
for upgrading or launching with --disable-smart-routing.
Use ug opencode --model system.ai.glm-5-3 (or -m) to select a configured
model for one launch. OpenCode's provider/model form is also accepted.
Unknown Databricks models produce an error; this option does not add models
to discovery or change ug's saved default.
ug antigravity (or ug agy) runs Google's Antigravity CLI 1.2.15 or later in its
Enterprise Gateway mode, so it never asks for Google sign-in. It offers the workspace's
Gemini models under the names Antigravity knows them by (system.ai.gemini-3-8-flash is
gemini-3.8-flash) and explicitly selects the newest for each launch, including headless
sessions. A local proxy refreshes the Databricks token
for the whole session and maps each name back to its Databricks model. --model accepts
either name, or one of Antigravity's thinking tiers such as gemini-3.8-flash-high.
--provider routes through a Gemini Enterprise Model Provider Service, as with
ug gemini; choosing External Models in ug configure saves one. When the service declares
several models, configure starts on the newest; when it serves any model without declaring
one, configure asks which to start on. --model picks another at launch. Claude, GPT, and open-source models aren't offered, because Antigravity runs
tools only for models it recognizes. ug installs the CLI with Google's installer when it
is missing (macOS and Linux). On a workspace with a managed config, which can't enable
Antigravity yet, run ug agents add antigravity to use it self-managed.
ug copilot lists every Claude and GPT model you can use on the workspace in
Copilot's /model picker, and you can switch between them mid-session. Claude
models use the Anthropic Messages API, GPT-5 and newer use Responses, and older
GPT models use Chat Completions. Gemini and open-source models aren't offered, except under
--model-location (below).
ug copilot --model claude-opus-5-5 (or system.ai.claude-opus-5-5, or Copilot's
own dbx-anthropic/system.ai.claude-opus-5-5) picks the model a session starts on;
an unknown or unsupported model fails before Copilot starts and lists the
available ones. ug passes Copilot a per-session model registry, so your own
~/.copilot/providers.json and COPILOT_PROVIDER_* settings apply only to plain
copilot. Use plain /model, not /model --global, inside ug copilot: a
global choice is saved for plain copilot too, where the Databricks models don't
exist. Requires Copilot CLI 1.0.91 or newer.
ug copilot runs Copilot against a loopback proxy for the session. Copilot holds only
a random session secret, kept in the session's ~/.copilot/ug-providers-<id>.json
registry (readable only by you, deleted when the session ends); the proxy adds a fresh Databricks token to
each gateway request, so OAuth sessions keep working past token expiry without a
restart, and no Databricks token is written to disk. If the Databricks sign-in itself expires,
Copilot shows a "Databricks sign-in expired" error; run databricks auth login and
restart ug copilot. Proxy errors are logged to ~/.ucode/logs/copilot-proxy.log.
So that AI Gateway's usage table can tell sessions and subagents apart, the proxy sends each request
a session-id header: the UUID of the session you resume with --session-id or --resume, or for
a new session a new one that ug passes to Copilot as --session-id. A session picked another way
(by name, --continue) gets an id of that launch only. A subagent's requests also get a
thread-id of that session and the subagent. Copilot Chat in VS Code sends its chat's id as
session-id.
ug copilot --provider <catalog>.<schema>.<name> routes the session through a Model Provider
Service instead, and /model lists that service's models: Claude models of an Anthropic or
Bedrock service, and the chat models of an OpenAI, Azure OpenAI or Microsoft Foundry service. For a service that
allows every model, /model lists the models the gateway reports for it, which the provider
account may not serve; name the one to start on with --model. Services that relay a Claude subscription work only with Claude Code. Interactive
ug configure offers the matching services under External Models, and a managed workspace
config can set one for Copilot. ug copilot --model-location <catalog>.<schema> uses the model
services of one schema instead: services named like Claude or GPT models use their usual API, and
the rest go through the gateway's Anthropic endpoint, as for Claude Code.
ug claude --provider <catalog>.<schema>.<name> and ug codex --provider ... also
accept custom Model Provider Services. The upstream endpoint must natively support
Anthropic Messages for Claude or OpenAI Responses for Codex; MPS calls do not translate
between APIs. Declare those APIs on the service's targets. Custom deployment names are
preserved and can be selected with --model.
For every supported provider, Codex accepts only targets declared with OpenAI Responses
(openai/v1/responses). Restricted services with no compatible targets are hidden from
the provider picker and rejected when selected explicitly.
ug codex --provider <catalog>.<schema>.<name> on an Amazon Bedrock (runtime) service turns off Codex's
built-in web_search for that launch, because Bedrock's Responses API rejects it, and registers the
system.ai.web_search MCP service instead. Nothing is added if that service is already configured
for Codex. Bedrock Mantle and other providers keep the built-in tool.
Without a managed workspace config, ug claude automatically discovers gateway
models for Claude Code's /model picker. Discovery defaults to system.ai when
no provider or model location is selected. Use --provider or --model-location
to select another model source; managed workspace configs control their own sources.
ug claude --provider <catalog>.<schema>.<name> also supports Claude deployments on
Microsoft Foundry. For every provider, Claude uses only targets declared with Anthropic Messages
(anthropic/v1/messages); MPS requests do not translate other APIs to Messages. Restricted
services with no compatible targets are rejected. Deployment names are passed unchanged.
When no target identifies a Claude family, the first compatible target becomes the default.
Use --model <deployment> to select another deployment or a model on an allow-all service
without declared targets.
Interactive ug configure also offers a Custom Model Location (<catalog>.<schema>) for
Claude Code, Codex and Copilot alongside Databricks Hosted and External Models. The choice is saved
with the rest of the configuration, so later ug claude / ug codex / ug copilot launches use it; an
explicit --provider or --model-location still overrides it for that launch.
ug codex validates discovered models with the installed Codex binary and publishes
them to ~/.ucode/codex-model-catalog.json, referenced by shared ~/.codex/config.toml
for Codex App. Managed static lists use the same path during ug configure. The
latest refresh supplies the app's catalog; custom catalogs (including Isaac's) and
custom providers are preserved. The app's gateway provider and authentication must
already be configured. Validation covers the local Codex binary.
Codex loads the catalog at app-server startup. When ug reports a catalog change,
finish active tasks, restart the app server on the connected host, then reconnect.
Use codex app-server daemon restart for a standalone managed daemon; otherwise
restart the process or application that owns the server. Reconnecting or reopening
the desktop app can reuse a remote server with the old list.
ug removes its shared reference on discovery/validation failure, reconfiguration,
revert, or before installing/updating Codex. After an update, run ug codex to refresh
discovery or ug configure for a managed static list, then restart the app server.
ug configure
ug configure --agents claude,codex
ug configure --workspace https://first.databricks.com
ug configure --profile DEFAULT --agents claude,codex
ug configure --user
ug configure --agent claude --model-location main.models
ug configure --agents claude,codex --provider main.default.anthropic--model-location <catalog>.<schema> and --provider <catalog>.<schema>.<name> pick the model
source without the interactive picker, so a script can configure it. --model-location applies to
Claude Code, Codex, and Copilot (CLI and VS Code); --provider also applies to Gemini CLI. Either
needs --agent/--agents, and they cannot be combined. Cursor may share the run but takes no
source. The choice is saved for later launches, and each one replaces the other. A bad Copilot
source fails before anything is saved. A managed config that enables agents names the source itself
and rejects both flags.
By default, ug configure writes both the per-user settings and the machine-wide Claude Code and
Codex managed settings with sudo, with or without a terminal: run headless as root (or with
passwordless sudo), since a write that can't be authorized fails the command.
--global writes only the machine-wide managed settings and leaves every per-user setting alone:
~/.claude/ucode-settings.json, ~/.codex/ucode.config.toml and ~/.codex/config.toml, user MCP
servers, skills, Databricks AI Tools, and Desktop/Cowork user settings. Claude Code and Codex
(0.134.0 or newer) have machine-wide CLI settings; macOS also supports Desktop MDM provisioning.
Other CLI agents are skipped with a note, so a run that names only them does nothing. It fails for --mcp, --enable-databricks-ai-tools, a subscription
relay, and UG_SKIP_OS_SETTINGS. It also fails when ug or its Python is in a user's home folder
(checked through symlinks), since every user's agents run them: install ug in a shared location
first, as scripts/mdm/macos-provision.sh does with UV_TOOL_DIR, UV_TOOL_BIN_DIR, and
UV_PYTHON_INSTALL_DIR. Workspace MCP servers that only user settings can hold, the
web_search MCP server, and a static Codex model list are skipped with a warning. ug still saves its
own state in ~/.ucode and your Databricks login. Only that run is limited: each user's first
launch writes their per-user settings as usual.
--user skips them, like UG_SKIP_OS_SETTINGS, and needs no sudo; use it when you launch through
ug. UG_SKIP_OS_SETTINGS=1 neither writes nor checks the OS-managed files: ug trusts whatever is
there and the agents apply their native precedence. Configure fails while a managed file for the agent exists, since managed settings take
precedence; later launches use whatever files are present.
The choice is saved for launches after a successful configure; ug configure without --user
and ug revert return to the default, which writes both.
--user also fails for a workspace that publishes a managed config, which must be installed
machine-wide: run ug configure without --user, or ask your administrator to run
ug configure --global.
For Claude Desktop, default ug configure and --user both write only the user's
3P JSON profile, generated marketplace, and native Cowork registration/cache. They leave
root files untouched. Explicit --global skips those user-level Desktop writers; machine
policy and plugin provisioning use the macOS MDM path. CLI-agent scope handling is
unchanged. If Desktop has not initialized a Cowork account directory, ordinary configure
skips plugin setup until that directory exists. See
Desktop plugin installation.
For macOS MDM deployment, run ug configure --agents claude --global --workspace <url>
with a preinstalled shared runtime. Machine writes request sudo when needed. This publishes Desktop's managed plist with
connectors/tool search and an organization plugin containing skills/hooks. Desktop loads
the plugin directly; no LaunchAgent or per-user marketplace refresh is installed.
It leaves Desktop's user profile and marketplace source unchanged. Windows and Linux skip
Desktop under --global.
Desktop provisioning failures warn without failing CLI setup. Ordinary ug revert attempts
user and MDM cleanup, requesting sudo for machine files when needed.
Provisioning credentials stay separate from users' Desktop authentication.
See MDM prerequisites, deployment, and validation.
An account custom URL (such as https://acme.cloud.databricks.com) serves every workspace of the
account. Select the workspace the way the Databricks CLI does:
ug configure --workspace 'https://acme.cloud.databricks.com/?w=1234567890123456'
ug configure --profile acme # a profile whose host is the custom URL and that has a workspace_id
ug claude --workspace 'https://acme.cloud.databricks.com/?w=1234567890123456'?o= and ?workspace_id= work too. ug keeps the custom URL as the workspace URL, gets the account
token from the profile, and sends the workspace id as X-Databricks-Org-Id and
X-Databricks-Workspace-Id on every request to that host: its own requests, its proxies, and the
headers it writes for each agent. On a host that serves one workspace the id is ignored. With no
profile for the host yet, the first login names one ug-<name>.
Not supported yet on these hosts: disaster-recovery stable connection ids, signing in to an MCP
service connection that needs your own login, and the MDM bootstrap script. MCP servers are
registered through ug mcp-proxy, never as the agent's own OAuth connection.
ug denies Claude Code's native WebSearch and registers its own web_search MCP. For one launch,
UG_CLAUDE_SERVER_SIDE_WEB_SEARCH=1 ug claude instead uses the Unity Gateway's server-side search,
writing no file. If the OS-managed settings, their managed-settings.d
drop-ins, or the user settings deny WebSearch, ug warns and keeps its MCP for that launch.
To make it the default, run ug configure --enable-server-side-web-search (--disable-... undoes it;
omitting the flag keeps the saved choice). An explicit ug configure then also removes a bare
WebSearch deny from the OS-managed settings unless your admin settings request it, and ug revert
restores it only if that deny list wasn't edited since. ug never writes the deny to the managed file.
Relayed launches are unaffected.
ug --header "x-databricks-traffic-id: testenv://liteswap/<pod>" claude
UG_HEADERS="X-Team: eng" ug codex--header (repeatable) and UG_HEADERS (one Name: value per line) add headers to that launch's
Databricks requests only: Claude Code's and Codex's gateway requests, and ug's own requests
(workspace APIs, MCP proxy, web search, smart routing). A header already sent keeps its value.
Nothing is written to a config file.
- Codex: added to the launch's
-cprovider headers. - Claude Code: added by a mod, even when managed settings set
ANTHROPIC_CUSTOM_HEADERS. Onlyug configureinstalls or upgrades it beside the managed settings (with sudo, or as an administrator on Windows; not under--userorUG_SKIP_OS_SETTINGS); a launch never writes there. Without a terminal, configure needs passwordless sudo and an existing managed file. Another tool's copy of the mod, such as Isaac's, also counts. When none is enabled, or ug's is out of date, the launch warns and Claude doesn't send them.
Available coding agents are codex, claude, gemini, opencode,
kilo, copilot, pi, and antigravity. cursor can be included in --agents for MCP-only setup;
Cursor models still run through your Cursor account. vscode can be included in --agents to
install ug's extension for Copilot Chat in VS Code; it is configure-only, with no ug vscode
launch command.
UG_WORKSPACE can provide the default workspace. An explicit --workspace or
--profile takes precedence.
On macOS, Windows, and Linux, successful Claude Code configuration also creates and selects a dedicated Claude Desktop gateway profile. Its model list includes only Claude-named IDs; Claude Code's catalog is unchanged. Desktop setup errors warn without failing Claude Code configuration. See Claude Desktop setup for authentication, profile preservation, and native validation limits. When managed Claude tracing is enabled, the same profile configures Desktop's native OTLP trace export with a refreshing headers helper; no background service is needed. Anthropic subscription relay profiles use one helper to supply the short-lived Claude subscription token and Databricks gateway token on macOS, Windows, and Linux.
Use ug mcp add to register Databricks MCP servers for coding agents. Cursor
Agent supports MCP only and requires cursor-agent on PATH.
Run ug mcp add without options to browse services by name, UC location,
and status. ✓ means configured (or managed by the workspace); ✗ means not configured.
Configured and managed services stay visible as read-only rows. [ ]/[x] indicate
what you select for this operation; [-] marks a read-only row.
Highlight a service to see its description, creator, and creation/update dates. Type to filter names or UC locations, use Space to select, and Enter to save. Page Up/Down scrolls the detail pane. Narrow terminals shorten cells and show status symbols; the detail pane retains the full location and status.
Use ug mcp add to add servers without removing existing registrations:
ug mcp add --location system.ai
ug mcp add --names system.ai.slack,system.ai.github
ug mcp add --agents claude,codex --location system.ai
ug mcp add --agents cursor --names system.ai.github --workspace https://first.databricks.com
ug mcp add --agents codex --names system.ai.github --profile DEFAULT--agents adds MCP servers without changing an agent's models. Claude Code and
Codex work even if their CLI is not on PATH: UG writes their user MCP config
directly. If that file already exists, UG detects the client without its CLI.
This works on macOS, Windows, and Linux; other agents need their CLI on PATH.
Without a CLI, status shows the saved config but cannot check the connection.
--workspace or --profile selects the workspace on a fresh setup. To switch
an existing setup, run ug configure --workspace <url> first. The switch uses
that workspace's saved MCP servers; switching back restores the previous ones.
Remove configured servers:
ug mcp remove
ug mcp remove --agents codexList configured servers and their connection status:
ug mcp list
ug mcp list --agents claude,codexConnection-backed Unity Gateway MCP services use native HTTP OAuth in Claude Code,
Codex, and Cursor when the workspace publishes a compatible client. Claude Code
uses its URL-based client ID metadata document; if it is unavailable, ug uses
the local ug mcp-proxy stdio server with the Databricks CLI's OAuth client.
Other servers and agents also use that proxy. When a proxied connection needs
provider authentication, UG opens the workspace's MCP service sign-in page and
waits up to five minutes for the selected CLI profile's user credential, then retries
the original request. Use the same Databricks account in the browser and CLI profile.
If no browser opens, use the URL in the MCP server log; click Login if the provider
popup is blocked. This flow requires the workspace's MCP service login page and user-credential API;
it does not require CLI auth login --resource or a CLI upgrade.
V2 Unity Gateway servers can be added with typed selectors such as
vector-search:main.docs, uc-functions:main.tools, external:<name>,
genie-space:<space-id>, or app:<name>.
UG automatically shares the MCP proxy across agents to reduce memory usage while keeping each connection's session and credentials separate. No configuration changes are needed. If a proxy connection closes unexpectedly, reconnect the MCP server in your agent.
Claude-only setup also discovers GPT models for its generated web_search
server; installing or configuring Codex is not required. Search registration
requires an available Responses-capable model.
Claude's generated web_search server uses the same saved custom OAuth CLI
profile as its harness, when configured. It stores the profile name, not an
access token, and refreshes credentials for search requests. This does not
change search permissions.
The built-in search server runs up to four searches concurrently. A slow search does not block tool discovery or another search's result. Additional searches wait for a worker. Cancelling a queued search prevents it from running; an active search retains its worker until its blocking request finishes, and its response is discarded. Closing the input stream drains accepted searches, so shutdown can wait for the existing authentication and HTTP timeouts. Input failure or interruption cancels queued searches and waits for active requests to finish. This removes local serialization without changing the backend model or speeding up an individual backend request.
Launchers that supply their own search server can first query
ug mcp web-search --capabilities. Contract version 1 supports setting
UCODE_CLAUDE_WEB_SEARCH_PROVIDER=external-if-safe on the ug child process only
when the capability response advertises that automatic_provider value.
The default (unset or ucode) retains standalone ug search. External mode
does not create, update, or delete saved search registrations. Generated
helpers carry --managed-by-ucode. Only the launch override created after
ownership verification exposes no tools; copied helpers and custom registrations
retain their tools even when they inherit external provider selection.
For an existing generated web_search entry, ug verifies its saved ownership
fingerprint and uses a launch-only MCP override pointing at the current ug
installation. This also handles older helper executables. Disabled entries
are preserved without launch overrides, and --strict-mcp-config excludes saved registrations without
an override. Unknown ownership, overlapping config scopes, or command-based
MCP policies produce a warning and retain the existing provider; duplicate
providers may remain. Explicit external selection instead fails on a conflict.
Standalone refreshes preserve edited user entries and project/local servers.
If no search model is available, they retain ownership of the installed entry so a
later refresh or external-provider launch can still verify it.
The selection does not authorize search or remove any permission denial.
Concurrent setup still uses ug's existing whole-workspace state writes. A stale
ownership fingerprint safely preserves the server and prevents automatic handoff;
this contract does not make shared setup transactional.
Unity Catalog Skills can be registered as MCP tools or downloaded into local
agent skill directories. Run ug skills add without selectors to browse individual
skills in the same table and metadata pane as the MCP browser, plus the bundle name.
✓ Installed requires a recorded download of that exact UC skill with SKILL.md still
present at every target agent directory (--path, or your home directory). A matching
bundle name from another schema or metastore does not qualify. Unattributed local
bundles and incomplete installations show ✗ Not installed, with an explanation in the
detail pane. Installed skills remain selectable for updates.
Missing metadata is shown explicitly. Created by is the UC creator, which may
differ from the author of the bundle.
# Set up the Databricks skills MCP so your agents can create and manage skills through ug.
ug skills
# List configured skills and how each was configured.
ug skills list
# Download every skill in a schema into your local agent skill directories.
ug skills add --location main.default
# Download specific skills by fully-qualified name (may span schemas).
ug skills add --names main.default.my-skill,ml.prod.other-skill
# Add a schema to the MCP connection scope, exposing its skills as MCP tools.
ug skills add --location main.default --via mcp
# Interactively pick downloaded skills to delete.
ug skills remove
# Delete a specific downloaded skill by fully-qualified name.
ug skills remove --names main.default.my-skill
# Drop a schema from the MCP connection scope.
ug skills remove --location main.default --via mcp| Command | Description |
|---|---|
ug status |
Show workspace, generated files, models, and skill MCP scope |
ug configure |
Configure workspace, models, agent files, and optional Databricks AI tools |
ug configure --dry-run |
Preview config changes without writing files |
ug mcp add |
Add MCP servers without removing existing registrations |
ug mcp remove |
Unregister configured MCP servers |
ug mcp list |
List configured MCP servers and connection status |
ug agents add <agent> |
Allow a non-admin-enabled agent to run self-managed |
ug agents remove <agent> |
Remove an agent from your self-managed list |
ug agents list |
Show the admin-managed and self-managed agents |
ug skills |
Set up the Databricks skills MCP so agents can create and manage skills |
ug skills list |
List configured skills and how each was configured |
ug skills add |
Add skill MCP scopes or download skills |
ug skills remove |
Remove skill MCP scopes or downloaded skills |
ug export |
Print or write portable managed config JSON |
ug doctor |
Diagnose local setup and offer fixes |
ug usage |
Show Unity Gateway spend and budget |
ug web |
Open the Unity Gateway page for your workspace in a browser |
ug revert |
Clear saved state and restore backed-up config files |
ug upgrade |
Upgrade Unity Gateway |
ug usage shows up to five Unity Gateway budget limits with the highest usage
percentages, with a short budget ID on each entry. It tells you when more limits
exist. Run ug usage --all to show every limit. Both commands use your configured
workspace login.
A launch (ug claude, ug codex) uses the workspace's managed coding agent config that
ug configure last saved and does not refetch it. After an admin changes that config, run
ug configure to pick it up.
Databricks AI Tools are installed only by ug configure, never by agent launch
commands. Use --enable-databricks-ai-tools or --disable-databricks-ai-tools
with ug configure to control installation.
Smart routing passes generated agents through a per-launch --plugin-dir,
alongside --settings, without persistent plugin registration. One temporary
directory holds the settings, socket, and plugin and is removed when the launch
finishes or fails. Existing hook configuration and disable/revert behavior are
unchanged. Native daemon/background propagation of the plugin remains unverified.
The routing notice names the generated agent selected for launch and its model. Claude Code's own task header can still show the agent type the parent originally requested. That name may contain a different model; it is not the routing result.
The local ~/.ucode/<agent>-smart-routing-decisions.jsonl logs also retain the
candidate models, their harnesses, and the router name sent with each recorded
decision. Feedback investigations can compare the selection with that original
menu without querying the router again.
Claude and Codex routing reasons summarize the task profile in plain language, such as
"This task has a clear target and limited scope." A separate sentence explains when
model availability requires a higher tier. Custom gateway notices are retained, and
older or unrecognized responses keep their original wording. Diagnostic records keep
the displayed reason in rationale and the gateway's explanation in raw_rationale.
Codex decision records cap each reason at 1,000 characters and identify the assignment
by task_sha256 (SHA-256 of its UTF-8 text) and task_length (characters). The router
and native child still receive the complete assignment. Reasons can quote task content,
so these logs may still contain sensitive details. Claude's audit format is unchanged.
On Windows, Claude smart routing uses subagent hooks only. If first-prompt routing is enabled, ug warns and falls back to subagent routing because the first-prompt wrapper requires a Unix terminal. The generated shell hooks expect Git Bash; PowerShell-only setups are not covered.
--enable-smart-routing and a workspace config with smart_routing.enabled turn routing on
through SMART_ROUTER_CONFIG_VERSION: they keep a known version and otherwise select
subagent_orch_v0_claude_only. For Claude, that routes subagents and turns on Smart Router
Orchestrator while the main session stays on its default model. Codex stays unrouted and
without orchestration under this default, and a Codex launch that turns routing on this way
warns and runs without smart routing: --enable-smart-routing says smart routing on Codex is
currently not supported, and workspace smart routing says it is enabled for Codex in this
workspace but currently only supported for Claude Code. ug codex --help hides
--enable-smart-routing and --disable-smart-routing (the Smart Router skill still uses them)
and notes that Smart Routing is currently only supported for the Claude Code harness.
Like any version, it overrides individually set routing env vars. --disable-smart-routing
turns routing off for the launch, including over a workspace config.
An explicit --model, from ug claude --model or a launcher such as Omnigent, keeps
subagent routing when first-prompt routing is off; the main session stays on that model.
With first-prompt routing on, an explicit model still skips routing.
When a model response launches a subagent, UG buffers that step and removes premature model claims before displaying or storing them. After launch, UG renders the parent's report directly from that request's child records: animal name, verified model, completion state and the recorded child answer. No special parent output format or Stop-hook retry is required. This replaces free-form parent summaries for that delegated request. Tool calls remain available, background completion follows the same path, and a fresh main-agent request replies normally. Routing-enabled responses are buffered until each model step completes.
Smart routing now requires Codex 0.164.0
or newer, including workspaces that already enable managed smart routing. Users on
Codex 0.156–0.163 who previously launched successfully must upgrade or explicitly
run ug codex --disable-smart-routing. UG offers its usual upgrade prompt for a
known older version and checks the result before launching. Declining, failing, or
remaining below 0.164.0 after the upgrade keeps the routed launch blocked. This
intentional requirement ensures native v2 provides readable delegated assignments;
UG does not silently disable routing. Ordinary launches require Codex 0.156.0
and newer. The general integration CI baseline is 0.156.0; routing cases use
0.165.0.
An inconclusive Codex version probe is retried once with a longer timeout. If the
version is still unknown, UG stops without offering or running an update and asks
you to check codex --version. --disable-smart-routing also bypasses this routing
version check.
For a routed launch, UG's -c overrides take precedence over saved values for
features.multi_agent_v2.non_code_mode_only (set to false),
features.multi_agent_v2.root_agent_usage_hint_text, and
features.multi_agent_v2.subagent_usage_hint_text (set to UG's collaboration guidance).
Custom values for these fields do not apply during that session. The saved config
files are unchanged, as are native delegation-mode controls. Requests use the
configured Databricks provider directly. All routed Codex launches use the app-server
interposer, including subagent-only presets. First-prompt model selection still follows
the selected preset.
Smart Router toggles keep every conversation loaded and do not interrupt any turn. The toggle turn finishes normally with its original routing attribution; the next main turn receives the new state. UG adds no user prompt or automatic continuation. Existing subagents keep running with their original attribution; new children, including descendants spawned by an old child, get the latest state through the spawn hook. Repeating the current state leaves session controls unchanged.
Backend attribution uses JSON in x-codex-turn-metadata. Every routed launch adds
smart_router_recipe_name; main turns add smart_router_state (on or off).
The hook stamps child task names with __sr_on or __sr_off, which Codex places in
agent_name. Parse only the final path segment: /root/old__sr_on/new__sr_off
means off for that grandchild. A child's marker takes precedence over main state.
Off is recorded as DISABLED; on uses the recipe name. Older clients can fall back
to Databricks-Smart-Router-Recipe. These values describe client-requested routing,
not proof that the router selected a different model. Native internal agents that
bypass spawn_agent have no guaranteed marker. Reserve smart_router_state for
per-turn metadata; a static Codex responses_api_metadata entry with that name
would override dynamic values.
Use SMART_ROUTER_CONFIG_VERSION at launch to select a smart-routing configuration.
Each version defines separate Claude Code and Codex flag mappings; the existing versions
use identical mappings for both agents. The Claude-only version disables routing for Codex:
| Version | Routed agents | Subagent routing | First-prompt routing | Orchestrator |
|---|---|---|---|---|
first_prompt_and_subagent_no_orch_v0 |
Claude, Codex | On | On | Off |
subagent_only_v0 |
Claude, Codex | On | Off | Off |
subagent_only_v1 |
Claude, Codex | On | Off | Off |
subagent_orch_v0 |
Claude, Codex | On | Off | On |
subagent_orch_v1 |
Claude, Codex | On | Off | On |
subagent_orch_v0_claude_only |
Claude | On | Off | On |
first_prompt_and_subagent_no_orch_v0 routes the first prompt and subagents without
orchestration: ENABLE_SMART_ROUTING_V2=1, ENABLE_SMART_ROUTING_SUBAGENT_ONLY=0, and
ENABLE_SMART_ROUTER_ORCHESTRATOR=0. Every other version routes subagents only;
subagent_only_v1 and subagent_orch_v1 route the same way as their _v0 versions.
subagent_orch_v0_claude_only keeps Claude's subagent_orch_v0 flags (0, 1, 1)
and sets all three flags to "0" for Codex. Codex uses its ordinary launch and
managed default model, without routing or orchestration. --enable-smart-routing and
workspace smart routing keep this version, so Codex stays unrouted: ug warns and launches it
like a plain ug codex, without the Smart Router skills or routing hooks.
SMART_ROUTER_NAME still selects the router independently of the preset.
Smart-routed Claude and Codex sessions install smart-router. The subagent_orch_v0
and subagent_orch_v1 versions also install and activate the bundled smart-router-orchestrator skill.
--enable-smart-routing and workspace smart routing select subagent_orch_v0_claude_only, which
installs both skills for Claude only; Codex gets neither. For example:
SMART_ROUTER_CONFIG_VERSION=subagent_orch_v0 ug claudeThe version takes precedence over conflicting legacy flags. Once the agent is selected,
UG expands its mapping into
ENABLE_SMART_ROUTING_V2, ENABLE_SMART_ROUTING_SUBAGENT_ONLY, and
ENABLE_SMART_ROUTER_ORCHESTRATOR for the launched session. When the version is
unset or empty, these legacy flags retain their existing behavior, including
first-prompt routing through ENABLE_SMART_ROUTING_V2=1. Unknown versions are ignored:
no preset is applied, the inherited environment is unchanged, and commands continue normally.
--disable-smart-routing and session on/off controls apply after expansion;
--enable-smart-routing and workspace smart routing keep a known version.
Orchestration is off by default unless --enable-smart-routing or workspace smart routing
selects subagent_orch_v0_claude_only, which enables it for Claude only.
Version names require an explicit suffix. Future revisions use new _v1, _v2,
etc. names without changing existing versions.
Version definitions require both Claude and Codex mappings and fail validation at module import if any flag in
SMART_ROUTING_ENV_KEYS is missing, has a value other than "0" or "1",
or an unknown flag is present. Register new managed flags in that tuple and
explicitly set them for both agents in every version.
Use ug codex in the same command for Codex. Smart Router Orchestrator assigns bounded work
to explorer, researcher, worker, tester, and reviewer roles while the root plans,
integrates, and verifies results. Easy tasks and explicit requests not to delegate
stay in the root.
Claude and Codex routing panels add [orchestrator on] to the Subagent line
only when orchestration is active. When it is off, they show the normal subagent
name. The label reports the session mode; it does not identify whether a particular
delegation came from the workflow or an explicit user request.
Once opted in, orchestration follows the existing smart-routing launch eligibility and session controls. Turning Smart Router off through its skill stops new automatic delegation; turning it on restores orchestration only in opted-in sessions. Explicit user requests for subagents still use normal harness behavior while routing is off. If Codex cannot read or write the private session controls due to permissions, the skill requests native approval for the exact toggle command. Declining leaves routing unchanged; the directory permissions and sandbox configuration are preserved. Other write failures, such as a full disk, report the underlying error without requesting approval. Stored skill files do not activate orchestration without an opted-in configuration, or in non-routed sessions. Existing Isaac pilot gating and UG launch exclusions still apply.
Hooks refresh orchestration state before each prompt and after compaction. A state change made outside the conversation is observed at the next hook; model routing still checks the controls for each subagent.
UG supplies its own hooks; Codex combines them with existing hooks and applies project trust. Smart routing selects subagent models; separate role-model preferences are ignored and their files are left untouched. See the bundled Smart Router Orchestrator documentation for details.
ug backs up files before overwriting them. ug revert restores backups.
| Tool | Managed files |
|---|---|
| Codex | ~/.codex/ucode.config.toml, shared catalog reference in ~/.codex/config.toml, ~/.ucode/codex-model-catalog.json, /etc/codex/managed_config.toml (Linux and macOS), C:\ProgramData\OpenAI\Codex\requirements.toml (Windows, written only from an elevated terminal; enforced by Codex 0.156.0 and later) |
| Claude Code | ~/.claude/ucode-settings.json, ~/.claude.json, /etc/claude-code/managed-settings.json (Linux), /Library/Application Support/ClaudeCode/managed-settings.json (macOS), C:\Program Files\ClaudeCode\managed-settings.json (Windows, written only from an elevated terminal) |
| Gemini CLI | ~/.gemini/ucode.env, ~/.ucode/.gemini-home/.gemini/settings.json |
| OpenCode | ~/.ucode/opencode-xdg/opencode/opencode.json, ~/.ucode/opencode-xdg/opencode/plugin/ucode-auth.js |
| Kilo | ~/.ucode/kilo-xdg/kilo/kilo.json, ~/.ucode/kilo-xdg/kilo/plugin/ucode-auth.js |
| GitHub Copilot CLI | ~/.copilot/ucode.env, ~/.copilot/mcp-config.json (or $COPILOT_HOME/mcp-config.json) |
| Pi | ~/.ucode/pi-home/.pi/agent/models.json, ~/.ucode/pi-home/.pi/agent/settings.json |
| Antigravity CLI | ~/.gemini/config/skills.json (adds ~/.agents/skills), ~/.gemini/config/mcp_config.json (ug's MCP servers only); the gateway is set per launch through AGY_LLM_GATEWAY_* variables |
| Cursor Agent | ~/.cursor/mcp.json |
| VS Code (Copilot Chat) | ug's databricks.unity-gateway-<version> extension under ~/.vscode/extensions/ (or ~/.vscode-insiders/extensions/), including the ug-config.json inside it; installed by ug configure --agents vscode, uninstalled by ug revert; your settings.json is never edited |
| Unity Gateway | /etc/unitygateway/managed-settings.json (Linux and macOS), ~/.ucode/refresh_ts.json, ~/.ucode/managed-state.json, ~/.ucode/managed-backups/ |
Workspace policy is root-owned but readable without sudo. Configure installs it only when the
workspace publishes a policy; launches check for updates every five minutes. Launches never
write workspace policy, even as root: they warn about changes and keep the installed policy
until ug configure (by an administrator or an IT provisioning run) updates it. Each distinct pending change warns once.
The installed workspace is authoritative: selecting a different one fails launch instead of
falling back to unmanaged behavior.
Refresh timestamps and pending-change hashes live in user-owned ~/.ucode/refresh_ts.json,
not in the protected policy file.
This policy is separate from agent-file backups and is not removed by ug revert.
See managed workspace policy for permissions and trade-offs.
Managed policy headers must not contain secrets: the policy is readable by all local users.
When ug configure sets up Codex with a relayed OpenAI provider, it also points the Codex app's
~/.codex/config.toml at a loopback relay served by the same login service below (plain codex
then uses it too). Like Claude Desktop, ug codex --provider doesn't change the app. Restart the
app and sign in with ChatGPT. A provider you already set is left alone; ug revert removes ug's
entries.
With workspace tracing enabled, run ug configure --agents codex on the machine
where Codex desktop's app server runs, then restart the app server once. This points
Codex's trace exporter in ~/.codex/config.toml at the existing CLI OTEL proxy, run
as a per-user service that starts at login; ug codex sessions keep their own proxy.
An exporter you already set is left alone. Disabling tracing or ug revert removes both.
| OS | Service | Diagnostics |
|---|---|---|
| Linux | systemd user service ug-codex-otel.service |
journalctl --user -u ug-codex-otel.service |
| macOS | LaunchAgent com.databricks.ug-codex-otel |
launchctl print gui/$(id -u)/com.databricks.ug-codex-otel |
| Windows | Scheduled task com.databricks.ug-codex-otel |
schtasks /Query /TN com.databricks.ug-codex-otel /V /FO LIST |
git clone https://github.com/databricks/unity-gateway
cd unity-gateway
uv sync
uv run pytest
uv run ruff check .For integration tests against installed ug and agent versions, see
tests/integration/README.md. The existing e2e
tests remain available separately:
UCODE_TEST_WORKSPACE=<db_workspace_url> uv run pytest tests/test_e2e.py -vTo add a new CLI agent, implement src/ucode/agents/<name>.py, register it in
src/ucode/agents/__init__.py, and add focused tests.
Desktop-app adapters live separately in src/ucode/agents/desktop/.
Desktop rendering consumes model IDs and headers from shared discovery/managed-config
parsing without revalidating or deduplicating them.
Claude Desktop profiles use Anthropic's documented application-data locations
on macOS, Windows, and Linux, with no profile-directory override. Windows and Linux require the app to have been opened once;
their native GUI, credential-helper, and inference flows still need validation.
Profiles are named Unity Gateway - <CLI profile name> and use one reserved UUID:
5b36a0b9-b56d-47cf-b6a4-0904e0bc14f6. Configure replaces that whole profile,
updates its metadata entry, and selects it. Switching workspaces replaces the same file.
Revert deletes that profile and entry, preserving unrelated profiles and metadata.
Only the previous selection is recorded in ~/.ucode/claude-desktop.json;
no original profile contents are saved for revert. Old random-ID and workspace-derived
profiles are left untouched. A valid JSON _comment field warns against manual edits;
native Desktop acceptance of that field still needs a smoke test.
Workspace-specific UUID normalization is removed; existing CLI URL handling is unchanged.
Claude Desktop profile updates wait up to five seconds for the file lock across platforms. A timeout leaves the operation holding the lock undisturbed. The Desktop auth helper retains its existing shared deadline.
- Databricks Unity Gateway overview
- Databricks Unity Gateway coding agent integration
- Databricks CLI authentication
- Monitor Unity Gateway usage
Please report security vulnerabilities to [email protected] rather than opening a public issue.
See LICENSE.md and NOTICE.md.
Use the Publish skills action to sync skill folders in your GitHub repository to Unity Catalog on each push. No notebook, job, or Unity Gateway CLI installation is required. After configuring Databricks authentication and UC permissions, add this step to your workflow:
- uses: databricks/unity-gateway/actions/publish-skills@main
with:
skills-directory: skills
target-schema: acme.team_skillsThe setup guide includes complete OIDC and OAuth
workflows, custom folder mappings, sharing permissions, and verification steps.
Use @main for automatic updates or pin a reviewed commit for reproducible runs.