Unity Gateway (ug)

Unity Gateway runs coding agents through Databricks AI Gateway. It configures Codex, Claude Code, Gemini CLI, OpenCode, GitHub Copilot CLI, and Pi, 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.

Requirements

• Python 3.12+
• uv
• npm, when an agent CLI needs automatic installation

Install

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

Migrating from ucode

Reinstall under the new distribution name:

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

Future upgrades can use ug upgrade or uv tool upgrade unity-gateway.

Launch Agents

Run the tool you want:

ug codex
ug claude
ug gemini
ug opencode
ug copilot
ug pi
ug cursor   # Cursor Agent, MCP-only

On 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.

Configure

ug configure
ug configure --agents claude,codex
ug configure --workspace https://first.databricks.com
ug configure --profile DEFAULT --agents claude,codex

Available coding agents are codex, claude, gemini, opencode, copilot, and pi. cursor can be included in --agents for MCP-only setup; Cursor models still run through your Cursor account.

UG_WORKSPACE can provide the default workspace. An explicit --workspace or --profile takes precedence.

MCP Servers

Register Databricks MCP servers for configured MCP-capable agents. Cursor Agent is MCP-only and is included when cursor-agent is installed:

Use ug mcp add to add servers without removing existing registrations:

ug mcp add --location system.ai
ug mcp add --services system.ai.slack,system.ai.github
ug mcp add --agents claude,codex --location system.ai

Remove configured servers:

ug mcp remove
ug mcp remove --agents codex

List configured servers and their connection status:

ug mcp list
ug mcp list --agents claude,codex

Every Databricks MCP server is registered as a local stdio server that runs ug mcp-proxy; the proxy refreshes Databricks OAuth tokens from your CLI profile. V2 AI 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>.

Skills

Unity Catalog Skills can be registered as MCP tools or downloaded into local agent skill directories.

# List configured skills and how each was configured.
ug skills list

# Add to existing MCP scope or downloads.
ug skills add --location main.default --mcp
ug skills add --location main.default
ug skills add --skill main.default.my-skill,ml.prod.other-skill

# Remove MCP scopes or downloaded skill files.
ug skills remove --location main.default --mcp
ug skills remove
ug skills remove --skill main.default.my-skill

Commands

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 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 AI Gateway spend and budget
ug revert	Clear saved state and restore backed-up config files
ug upgrade	Upgrade Unity Gateway

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.

Managed Files

ug backs up files before overwriting them. ug revert restores backups.

Tool	Managed files
Codex	~/.codex/ucode.config.toml, legacy ~/.codex/config.toml, /etc/codex/managed_config.toml (Linux and macOS)
Claude Code	~/.claude/ucode-settings.json, ~/.claude.json, /etc/claude-code/managed-settings.json (Linux), /Library/Application Support/ClaudeCode/managed-settings.json (macOS)
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
GitHub Copilot CLI	~/.copilot/ucode.env, ~/.copilot/ucode-mcp-config.json
Pi	~/.ucode/pi-home/.pi/agent/models.json, ~/.ucode/pi-home/.pi/agent/settings.json
Cursor Agent	~/.cursor/mcp.json
Unity Gateway	~/.ucode/managed-state.json, ~/.ucode/managed-backups/

Development

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 -v

To add a new agent, implement src/ucode/agents/<name>.py, register it in src/ucode/agents/__init__.py, and add focused tests.

Documentation

• Databricks AI Gateway overview
• Databricks AI Gateway coding agent integration
• Databricks CLI authentication
• Monitor AI Gateway usage

Security

Please report security vulnerabilities to security@databricks.com rather than opening a public issue.

License

See LICENSE.md and NOTICE.md.