| → / Space | Next slide |
| ← | Previous slide |
| Home | First slide |
| End | Last slide |
| Swipe | Touch navigation |
ug (formerly ucode) is the local CLI. Unity Gateway is the hosted gateway it points your agent at.
Companion to the ug quickstart in tool-governance.
A coding agent talks directly to its model vendor out of the box. There is no shared point where identity, limits, and usage records live, so the platform team has nothing to attach a control to.
No per-user or per-team ceiling. A looping agent can run for hours before anyone notices the invoice.
The platform team cannot see who called which model, how often, or at what cost.
Provider API keys copied into shells, dotfiles, and CI, each one a separate leak path.
Closing these gaps without slowing engineers down is the platform team's job. Routing the agent through the gateway is how you do it.
A local command that configures a supported coding agent and launches it so its model requests authenticate to the Databricks AI Gateway. Supported agents include Claude Code, Codex, Gemini CLI, OpenCode, Copilot CLI, Pi, and Cursor.
It is not the hosted gateway. Installing the CLI provisions no gateway infrastructure and grants no model access. Your administrator enables the gateway features and grants model access separately.
| Name | What it means |
|---|---|
ug | The local command to set up and launch a supported coding agent. |
ucode | The older command name, kept as a backward-compatible alias. Use ug for new work. |
unity-gateway | The Python package that installs both commands. |
| Unity Gateway | The hosted gateway. Older material calls it UAIG, and the workspace sidebar still says AI Gateway. |
ug handles configuration and authentication; the gateway handles model access and routing.
Callers need EXECUTE on the Unity Catalog model service, plus USE CATALOG and USE SCHEMA. Controls apply at the model-service, user, or group level, not baked into a laptop.
Bound request velocity so a looping agent cannot consume unbounded capacity, and one team cannot starve another.
Every call lands in system.ai_gateway.usage, and inference tables can capture request detail, so spend and volume attribute by user, team, and model.
Routing model traffic through a gateway is a real control, but it is a narrow one. Be precise about what it does not cover, or access degrades quietly.
Sending an agent's model calls through the gateway does not confine its filesystem or network. Tool access is a separate, deliberate step (see the next slide), and even then Unity Catalog governs the tools, which is not the same as an OS-level sandbox.
Which model an agent may call, which tools it may invoke, and what its process may touch on disk are three separate controls. ug and the gateway cover the first two; sandboxing stays its own layer. See Custom MCP Principles and the Authorization pillar.
Model routing gets the agent a model. This is the separate, deliberate step that gets it governed tools, and the governance stays in Unity Catalog rather than in the agent.
ug mcp add registers governed Databricks MCP servers with a supported agent: SQL, Unity Catalog functions, AI Search, and external connections. The agent gains tool access that Unity Catalog governs.
# register a governed MCP server with the agent
ug mcp add
Connect agents to governed Skills published in Unity Catalog, downloaded locally or loaded live through MCP, so the agent uses reviewed, versioned capabilities rather than ad hoc ones.
The local MCP proxy fetches a fresh OAuth token per request. That reduces expired-token interruptions during long sessions, and developers never hold or rotate credentials themselves.
MCP tool access is governed by Unity Catalog grants, not by an operating-system sandbox. Registering a tool decides what the agent may call, not what its process may touch on disk. Keep sandboxing as its own layer.
A task-aware router selects a capable, lower-cost model for each coding task. Use it for cost and quality selection rather than a fixed allocation.
Send configured percentages across destinations for a canary, an A/B comparison, or a gradual migration. Up to five destinations, totaling 100%.
Retry eligible failures such as 429 or 5xx down an ordered backup list, for availability when a destination fails. Retries follow the fallback order, not the split weights.
system.ai_gateway.usage records spend, and its routing_information field records the split and fallback decisions behind each call. ug usage gives a spend summary across coding tools, and usage lands in one dashboard rather than per-vendor consoles.
| Mechanism | What chooses the destination | Use it for |
|---|---|---|
Explicit --model | You name one service, which can still route internally. | Predictable service selection. |
| Traffic splitting | Your configured percentages. | Canary rollout, A/B testing, load distribution. |
| Fallbacks | A failure, followed by your ordered backup list. | Availability when a destination fails. |
| Smart Routing | A task-aware router picks a capable, lower-cost model. | Coding-task cost and quality selection. |
system.ai services, not your custom catalog services, and an administrator must enable it. The caller needs access to every candidate model, or routing reports a missing model.
A Unity Catalog service named catalog.schema.service, for example main.ai.coding_claude. Point every caller at that name.
Set traffic splits and ordered fallbacks on the service. Adjust them without touching any client, since callers only know the service name.
Grant EXECUTE on the service, plus USE CATALOG and USE SCHEMA. Callers use the service name, not Model A or Model B directly.
# stable front-door name; routing changes behind it ug claude --model main.ai.coding_claude ug codex --model main.ai.coding_openai
Send a harmless prompt through a separate test service and inspect system.ai_gateway.usage. The routing_information field shows the split or fallback decision. Validate across enough independent sessions, not one short session.
Native Anthropic requests need a Claude-backed service; native OpenAI requests need an OpenAI-backed service. A routing rule does not translate one provider protocol into another.
uv tool install git+https://github.com/databricks/unity-gateway, then ug --version. uv tool isolates the CLI's Python dependencies.
Clear conflicting ANTHROPIC_* and OpenAI or Codex provider overrides first, then run ug configure --workspace https://YOUR-WORKSPACE-HOST --agents claude,codex and sign in as yourself.
From your project directory, run ug claude or ug codex. A basic reply confirms a model round trip; your administrator can confirm the gateway usage record.
Choose a custom service for administrator-defined traffic policy. Choose Smart Routing for task-aware model selection. They solve different problems, so do not expect Smart Routing to honor a custom service's split.
The gateway governs model access, rate, and usage. Keep tool authorization, sandboxing, and data grants on their own layers.
Register governed tools with ug mcp add, review spend with ug usage, and rerun ug configure to add agents or change routing. Full setup, routing configuration, and troubleshooting live in the ug quickstart under tool-governance.