Integrate with coding agents

With the Azure Databricks coding agent integration, you can route traffic from coding agents like Claude Code, Codex CLI, Cursor, and Gemini CLI through model services in Unity Gateway. This provides rate limiting, usage tracking, and inference tables—with all controls configured at the model service, user, or group level.

Features

• Access: Direct access to various coding tools and models, all under one invoice.
• Observability: A single unified dashboard to track usage, spend, and metrics across all your coding tools.
• Unified governance: Admins can manage model permissions and rate limits through Unity Gateway at the model service, user, or group level.

Requirements

• A Azure Databricks workspace in a Unity Gateway supported region.
• Unity Catalog enabled for your workspace. See Enable a workspace for Unity Catalog.

Setup

The fastest way to get started is with the Unity Gateway CLI, which installs, authenticates, and configures supported coding agents with Unity Gateway in one command.

Use the Unity Gateway CLI (recommended)

The Unity Gateway CLI (ug) is the single entry point for running coding agents against Unity Gateway. It handles OAuth, writes each agent's config file, and routes traffic through any LLM or MCP server you've registered. Supported agents:

• Claude Code
• Codex CLI
• Gemini CLI
• OpenCode
• GitHub Copilot CLI
• Pi
• and more

To see all supported coding agents, run ug --help.

Step 1: Install the Unity Gateway CLI

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

Requires Python 3.12 or later and uv. This installs the ug command.

Step 2: Open a coding agent

Run the agent you want. On first launch, the Unity Gateway CLI prompts for your Azure Databricks workspace URL, authenticates, and writes the agent's config file automatically. Subsequent launches go straight to the agent.

ug claude     # Claude Code
ug codex      # OpenAI Codex
ug gemini     # Gemini CLI
ug opencode   # OpenCode
ug copilot    # GitHub Copilot CLI
ug pi         # Pi

The Unity Gateway CLI passes flags after the agent name through to the underlying tool, for example:

ug codex --full-auto

To configure multiple coding agents at the same time, run:

ug configure

To register Azure Databricks MCP servers (Unity Catalog functions, AI Search, SQL warehouses, and discovered external connections) with MCP-capable agents:

ug mcp add

To see your Unity Gateway usage summary for the last 7 days:

ug usage

For the full command reference, run:

ug --help

Dashboard

After coding agent usage is tracked through Unity Gateway, you can view and monitor your metrics in the built-in dashboard.

To open the dashboard, click Govern in the top right of the Unity Gateway page, then click Usage Dashboard. The built-in usage dashboard includes a Coding Agents tab with graphs for coding tool usage.

Manual setup

If you prefer to configure agents yourself, follow the instructions for:

• Claude Code
• Codex CLI
• Cursor IDE
• Gemini CLI

Claude Code

Step 1: Configure the Claude Code client

Add the following configuration to ~/.claude/settings.json. See the Claude Code settings docs for more details.

{
  "env": {
    "ANTHROPIC_MODEL": "system.ai.claude-fable-5",
    "ANTHROPIC_BASE_URL": "https://<workspace-url>/ai-gateway/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "<databricks_pat_token>",
    "ANTHROPIC_CUSTOM_HEADERS": "x-databricks-use-coding-agent-mode: true",
    "CLAUDE_CODE_USE_GATEWAY": "1",
    "ENABLE_PROMPT_CACHING_1H": "1",
    "ENABLE_TOOL_SEARCH": "1"
  }
}

Replace <workspace-url> with your Azure Databricks workspace URL and <databricks_pat_token> with your personal access token. To set a different default model, change ANTHROPIC_MODEL to any Unity Gateway model service, for example system.ai.claude-opus-4-6.

Step 2 (optional): Set up OpenTelemetry metrics collection

See Set up OpenTelemetry data collection for details on exporting metrics and logs from Claude Code to Unity Catalog managed Delta tables.

Codex CLI

Step 1: Install or update Codex CLI

Install or update to Codex CLI version 0.118 or later:

npm install -g @openai/codex@latest

Step 2: Create or update the Codex config file

Create or edit the Codex configuration file at ~/.codex/config.toml:

profile = "default"

[profiles.default]
model_provider = "Databricks"

[model_providers.Databricks]
name = "Databricks :re[ai-gateway]"
base_url = "<workspace-url>/ai-gateway/codex/v1"
wire_api = "responses"

[model_providers.Databricks.auth]
command = "sh"
args = ["-c", "databricks auth token --host <workspace-url> --output json | jq -r '.access_token'"]
timeout_ms = 5000
refresh_interval_ms = 1800000

Replace <workspace-url> with your Azure Databricks workspace URL.

Step 3: Authenticate to your workspace

First, make sure you have the Azure Databricks CLI installed. See Install or update the Databricks CLI for instructions.

Then authenticate:

databricks auth login --host <workspace-url>

Replace <workspace-url> with your Azure Databricks workspace URL.

Step 4: Start Codex

codex

To change the model, use /model.

Cursor IDE

To configure Cursor to use model services in Unity Gateway:

Step 1: Configure base URL and API key

1. Open Cursor and navigate to Settings > Cursor Settings > Models > API Keys.

2. Enable Override OpenAI Base URL and enter the URL:

   https://<workspace-url>/ai-gateway/cursor/v1
   

   Replace <workspace-url> with your Azure Databricks workspace URL.

3. Paste your Azure Databricks personal access token into the OpenAI API Key field.

Step 2: Add custom models

1. Click + Add Custom Model in Cursor Settings.
2. Add your model service name (for example, system.ai.claude-opus-4-6) and enable the toggle.

Step 3: Test the integration

1. Open Ask mode with Cmd+L (macOS) or Ctrl+L (Windows/Linux) and select your model.
2. Send a message. All requests now route through Azure Databricks.

Gemini CLI

Step 1: Install the latest version of Gemini CLI

npm install -g @google/gemini-cli@nightly

Step 2: Configure environment variables

Create a file ~/.gemini/.env and add the following configuration. See the Gemini CLI authentication docs for more details.

GEMINI_MODEL=databricks-gemini-2-5-flash
GOOGLE_GEMINI_BASE_URL=https://<workspace-url>/ai-gateway/gemini
GEMINI_API_KEY_AUTH_MECHANISM="bearer"
GEMINI_API_KEY=<databricks_pat_token>

Replace <workspace-url> with your Azure Databricks workspace URL and <databricks_pat_token> with your personal access token.

Use Open Source models with coding agents

Azure Databricks supports integrating open source (OSS) models, such as glm-5-2, with coding agents.

In addition to the requirements above, your workspace must also have access to the target OSS model.

OpenCode

Set up the Unity Gateway CLI as described in Use the Unity Gateway CLI (recommended), then select system.ai.glm-5-2 as your model.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "databricks-oss/<open source model service name>",
  "provider": {
    "databricks-oss": {
      "npm": "@ai-sdk/openai",
      "options": {
        "baseURL": "<workspace-url>/ai-gateway/mlflow/v1",
        "apiKey": "<databricks_pat_token>"
      },
      "models": {
        "<open source model service name>": {}
      }
    }
  }
}

opencode

Codex

Codex connects to Open Source models through the Open Responses API that Codex supports.

Set up the Unity Gateway CLI as described in Use the Unity Gateway CLI (recommended), then run:

ug codex --model <open source model service name>

For example, to use GLM 5.2 with Codex, run:

ug codex --model system.ai.glm-5-2

model = "<open source model service name>"
model_provider = "Databricks"

[model_providers.Databricks]
name = "Databricks :re[ai-gateway]"
base_url = "<workspace-url>/ai-gateway/codex/v1"
wire_api = "responses"

[model_providers.Databricks.auth]
command = "sh"
args = ["-c", "databricks auth token --host <workspace-url> --output json | jq -r '.access_token'"]
# Re-run the token command periodically so long sessions don't fail when the
# short-lived Databricks token expires.
timeout_ms = 5000
refresh_interval_ms = 1800000

codex

Set up OpenTelemetry data collection

Azure Databricks supports exporting OpenTelemetry metrics and logs from coding agents to Unity Catalog managed Delta tables. All metrics are time series data exported using the OpenTelemetry standard metrics protocol, and logs are exported using the OpenTelemetry logs protocol.

Requirements

• OpenTelemetry on Azure Databricks preview enabled. See Manage Azure Databricks previews.

Step 1: Create OpenTelemetry tables in Unity Catalog

Create Unity Catalog managed tables preconfigured with the OpenTelemetry metrics and logs schemas.

Metrics table

CREATE TABLE <catalog>.<schema>.<table_prefix>_otel_metrics (
  name STRING,
  description STRING,
  unit STRING,
  metric_type STRING,
  gauge STRUCT<
    start_time_unix_nano: LONG,
    time_unix_nano: LONG,
    value: DOUBLE,
    exemplars: ARRAY<STRUCT<
      time_unix_nano: LONG,
      value: DOUBLE,
      span_id: STRING,
      trace_id: STRING,
      filtered_attributes: MAP<STRING, STRING>
    >>,
    attributes: MAP<STRING, STRING>,
    flags: INT
  >,
  sum STRUCT<
    start_time_unix_nano: LONG,
    time_unix_nano: LONG,
    value: DOUBLE,
    exemplars: ARRAY<STRUCT<
      time_unix_nano: LONG,
      value: DOUBLE,
      span_id: STRING,
      trace_id: STRING,
      filtered_attributes: MAP<STRING, STRING>
    >>,
    attributes: MAP<STRING, STRING>,
    flags: INT,
    aggregation_temporality: STRING,
    is_monotonic: BOOLEAN
  >,
  histogram STRUCT<
    start_time_unix_nano: LONG,
    time_unix_nano: LONG,
    count: LONG,
    sum: DOUBLE,
    bucket_counts: ARRAY<LONG>,
    explicit_bounds: ARRAY<DOUBLE>,
    exemplars: ARRAY<STRUCT<
      time_unix_nano: LONG,
      value: DOUBLE,
      span_id: STRING,
      trace_id: STRING,
      filtered_attributes: MAP<STRING, STRING>
    >>,
    attributes: MAP<STRING, STRING>,
    flags: INT,
    min: DOUBLE,
    max: DOUBLE,
    aggregation_temporality: STRING
  >,
  exponential_histogram STRUCT<
    attributes: MAP<STRING, STRING>,
    start_time_unix_nano: LONG,
    time_unix_nano: LONG,
    count: LONG,
    sum: DOUBLE,
    scale: INT,
    zero_count: LONG,
    positive_bucket: STRUCT<
      offset: INT,
      bucket_counts: ARRAY<LONG>
    >,
    negative_bucket: STRUCT<
      offset: INT,
      bucket_counts: ARRAY<LONG>
    >,
    flags: INT,
    exemplars: ARRAY<STRUCT<
      time_unix_nano: LONG,
      value: DOUBLE,
      span_id: STRING,
      trace_id: STRING,
      filtered_attributes: MAP<STRING, STRING>
    >>,
    min: DOUBLE,
    max: DOUBLE,
    zero_threshold: DOUBLE,
    aggregation_temporality: STRING
  >,
  summary STRUCT<
    start_time_unix_nano: LONG,
    time_unix_nano: LONG,
    count: LONG,
    sum: DOUBLE,
    quantile_values: ARRAY<STRUCT<
      quantile: DOUBLE,
      value: DOUBLE
    >>,
    attributes: MAP<STRING, STRING>,
    flags: INT
  >,
  metadata MAP<STRING, STRING>,
  resource STRUCT<
    attributes: MAP<STRING, STRING>,
    dropped_attributes_count: INT
  >,
  resource_schema_url STRING,
  instrumentation_scope STRUCT<
    name: STRING,
    version: STRING,
    attributes: MAP<STRING, STRING>,
    dropped_attributes_count: INT
  >,
  metric_schema_url STRING
) USING DELTA
TBLPROPERTIES (
  'otel.schemaVersion' = 'v1'
)

Logs table

CREATE TABLE <catalog>.<schema>.<table_prefix>_otel_logs (
  event_name STRING,
  trace_id STRING,
  span_id STRING,
  time_unix_nano LONG,
  observed_time_unix_nano LONG,
  severity_number STRING,
  severity_text STRING,
  body STRING,
  attributes MAP<STRING, STRING>,
  dropped_attributes_count INT,
  flags INT,
  resource STRUCT<
    attributes: MAP<STRING, STRING>,
    dropped_attributes_count: INT
  >,
  resource_schema_url STRING,
  instrumentation_scope STRUCT<
    name: STRING,
    version: STRING,
    attributes: MAP<STRING, STRING>,
    dropped_attributes_count: INT
  >,
  log_schema_url STRING
) USING DELTA
TBLPROPERTIES (
  'otel.schemaVersion' = 'v1'
)

Step 2: Update env vars in your coding agent

In any coding agent with OpenTelemetry metric support enabled, configure the following environment variables.

{
  "OTEL_METRICS_EXPORTER": "otlp",
  "OTEL_EXPORTER_OTLP_METRICS_PROTOCOL": "http/protobuf",
  "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT": "https://<workspace-url>/api/2.0/otel/v1/metrics",
  "OTEL_EXPORTER_OTLP_METRICS_HEADERS": "content-type=application/x-protobuf,Authorization=Bearer <databricks_pat_token>,X-Databricks-UC-Table-Name=<catalog>.<schema>.<table_prefix>_otel_metrics",
  "OTEL_METRIC_EXPORT_INTERVAL": "10000",
  "OTEL_LOGS_EXPORTER": "otlp",
  "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",
  "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://<workspace-url>/api/2.0/otel/v1/logs",
  "OTEL_EXPORTER_OTLP_LOGS_HEADERS": "content-type=application/x-protobuf,Authorization=Bearer <databricks_pat_token>,X-Databricks-UC-Table-Name=<catalog>.<schema>.<table_prefix>_otel_logs",
  "OTEL_LOGS_EXPORT_INTERVAL": "5000"
}

For Claude Code, add these variables to the env block of your ~/.claude/settings.json file, along with "CLAUDE_CODE_ENABLE_TELEMETRY": "1" to turn on telemetry export.

Step 3: Run your coding agent.

Your data should propagate to the Unity Catalog tables within 5 minutes.

Next steps

• Model services
• Create and manage model services
• Query model services
• Discover and govern access to model services