Databricks Unity Gateway CLI: Set Up and Govern Coding Agents

When a team adopts Codex, Claude Code, Gemini CLI, and other coding agents, the hard part quickly shifts from choosing a model to operating the tools. Each agent can have a different authentication flow, model catalog, MCP configuration, skill directory, spending view, and audit trail.

Databricks introduced the Unity Gateway CLI on September 24, 2026 to put a common management layer in front of those agents. Developers keep the interfaces they already use, while administrators publish approved models, MCP servers, skills, spending policies, and tracing settings. The command is ug. The official documentation covers Codex, Claude Code, Gemini CLI, OpenCode, GitHub Copilot CLI, and Pi, with a more limited MCP-and-skills path for Cursor Agent.

The important distinction: this is not simply another free local coding assistant. It is aimed at organizations that already have a Databricks workspace and want consistent governance across several coding agents. You need Python 3.12 or later, uv, access to a Databricks workspace and its models, and administrator setup for some managed-configuration and tracing features that remain in Beta or Preview.

Developers can keep different coding agents while the organization applies one policy boundary for models, tools, spending, and tracing.

What problem does Unity Gateway CLI solve?

Every coding agent has its own configuration files and conventions. That is manageable for one person, but it creates drift across a team:

• Developers may connect different models or unapproved MCP servers.
• A new model default or budget policy must be recreated in several tools.
• Local tool calls and remote model requests land in separate logs, making failures difficult to reconstruct.
• A team may discover overspending without a consistent way to change defaults for new sessions.

ug does not replace every agent with a new interface. Before launch, it authenticates with the workspace, reads the published configuration, and prepares the agent-specific local settings. It then opens Codex, Claude Code, or another supported agent in its familiar interface. The common layer is therefore the policy and connection path, not the user experience.

Prerequisites and permission boundaries

Area	What to verify
Local machine	Python 3.12+, uv, and npm when an agent CLI needs automatic installation.
Workspace	A Databricks workspace URL and permission to use the required model services.
Managed configuration	A workspace admin must enable the Unity Gateway Managed Configuration Preview before publishing a shared configuration.
MCP and skills	Access to a listed server or skill does not automatically grant access to its underlying repository, database, or external service.
Unified tracing	Enhanced Unity Gateway Preview, Unity Catalog, and metastore-admin setup are required. The creator is the only reader by default.

Personal access token authentication is available, but OAuth is the normal first-run path. If a PAT is required, store it in a Databricks CLI profile rather than putting the secret directly into a shell command, then use ug configure --profile <name> --use-pat.

Install and launch an agent

Run the setup commands in a terminal. The official quickstart uses this sequence:

uv tool install git+https://github.com/databricks/unity-gateway
ug --version

# Launch an agent
ug codex
# or
ug claude

A version number confirms that the CLI is installed. On first launch, choose a Databricks workspace and sign in. ug then writes or manages the necessary agent configuration and opens the selected agent.

The installation and launch steps in the official quickstart. Source: Databricks Docs, checked September 30, 2026.

If your organization has not published a managed configuration, you can run an interactive setup or specify the target workspace and agents:

ug configure
ug configure --workspace https://your-workspace.databricks.com
ug configure --agents claude,codex

The repository also documents ug configure --dry-run for previewing changes. Use ug doctor to diagnose the local installation and agent files, and ug revert to restore backups created by the tool. For a production rollout, test the exact file changes on a separate device and account before distributing the CLI broadly.

Distribute MCP servers and skills consistently

MCP servers and skills solve different problems. An MCP server gives an agent access to data or actions. A skill provides reusable task instructions. Unity Gateway CLI can register MCP connections, download full skill folders into local agent directories, or expose published skills through MCP.

# Select approved MCP servers
ug mcp add
ug mcp list

# Select and download published skills
ug skills add
ug skills list

If you know the Unity Catalog names, you can add specific servers with a command such as ug mcp add --names system.ai.github,system.ai.slack. Skills can be installed for the current user or downloaded into a project with ug skills add --path "$PWD", which makes it easier to review and version the workflow with the repository.

Do not confuse discoverability with authorization. A developer may be able to see an MCP server without having access to the data behind it. The reverse concern also matters: tool descriptions and arguments can contain sensitive information even when the connection itself is approved. Start with least privilege and read-only scopes, require confirmation for changes, protect secrets, and retain tool-level audit evidence.

Support is not identical across agents

The official capability matrix lists Databricks models, external providers, MCP servers, and skills for both Claude Code and Codex CLI. Other agents have important differences:

• Cursor Agent: ug cursor configures MCP and skills only; model requests continue through the user's Cursor account.
• GitHub Copilot CLI: Databricks models, MCP, and skills are documented, but external-provider support is not listed.
• Pi: skills are supported, while MCP is not because Pi does not have an MCP client.
• Desktop and IDE surfaces: support can differ from the CLI, and some paths require manual setup or are marked as coming soon.

A shared configuration therefore does not make every client equivalent. Build a matrix for the agents and versions your team actually uses, then verify model, MCP, skill, tracing, and desktop or IDE requirements individually.

Three practical rollout patterns

1. Apply one GitHub tool policy to Codex and Claude Code

The goal is to prevent each developer from creating an unrelated GitHub MCP configuration. An administrator prepares the approved server and its read or write permissions in Unity Catalog, then includes it in the managed configuration. Developers sync with ug configure or the next launch and start with ug codex or ug claude. The acceptance test is not merely seeing the server name: both agents should reach approved repositories and reject actions outside the intended scope.

2. Version a code-review skill with a project

Instead of copying a review checklist into every chat, publish it as a skill and download it into a test repository with ug skills add --path "$PWD". Review the skill folder alongside the code. The expected output is a repeatable review that covers required areas such as security, tests, and migrations. A skill does not replace filesystem or command permissions, so keep execution controls separate.

3. Find repeated MCP failures before blaming the model

Enable unified tracing and direct records to a dedicated Unity Catalog table. Filter by service, status, principal, and time range to find repeated failures, oversized responses, or wasteful retries. Unified tracing is useful for diagnosis, but delivery is best-effort and some error traces are not guaranteed. Keep Databricks audit logs as the compliance system of record.

Spending and tracing caveats

ug usage can show current spend, total budget, and the percentage consumed. That output depends on administrator configuration: a budget ID must be linked to the managed configuration, and the relevant Preview and per-user blocking threshold must be enabled. The presence of the command does not mean every workspace will immediately show a budget.

The unified trace table may contain full prompts, responses, tool arguments, and identities. That is why only the creating metastore admin can query it by default. Before granting wider access, use Unity Catalog privileges and row filters to prevent teams from seeing one another's traces. Plan for delayed delivery, possible missing logs for some failures, truncation of attributes larger than 3 MiB, and a retention policy because the table does not expire automatically.

Finally, gateway governance does not replace local execution controls. It can govern model and MCP traffic while the agent's own sandbox still determines which files, commands, and credentials are available on the machine. If project isolation is part of your policy, pair this approach with a local boundary such as the one described in our GitHub Copilot app local sandboxing guide.

Troubleshooting order

1. Run ug --version to confirm the executable and installation path.
2. Run ug status to inspect the workspace, generated files, models, and skill MCP scope.
3. Run ug doctor for local configuration checks and suggested repairs.
4. If authentication or the model catalog is stale, use --refresh with Codex or Claude, or rerun ug configure.
5. For MCP failures, inspect ug mcp list, then check the underlying service and data permissions separately.
6. If managed settings do not appear, confirm that the Preview is enabled, a configuration is published, and the user has EXECUTE access to the model services.
7. To undo managed local changes, finish active work and review ug revert.

Who should use it?

Unity Gateway CLI is most relevant to organizations that already use Databricks and need one operating model for several teams, coding agents, model providers, MCP services, shared skills, budgets, and traces. It is not necessarily the shortest path for an individual trying Codex or Claude Code on a personal repository.

For a safer pilot, start with one test project, one or two models, and a read-only MCP server. Define success as more than a successful login: verify that only approved resources are visible, local changes can be reverted, trace readers are identified, and retention rules exist.

Official sources

• Databricks announcement: Deploy and manage coding agents at scale with the Unity Gateway CLI
• Databricks Docs: Coding agents quickstart
• Databricks Docs: ug CLI reference
• GitHub: databricks/unity-gateway

Sources checked September 30, 2026. Beta, Preview, and agent-support details can change, so verify the current documentation before deployment.

한국어로 읽기