Implementar agentes de codificação com gerenciamento de dispositivos móveis (MDM)

info

Beta

Este recurso está em Beta. Para usá-lo, um administrador do workspace deve ativar a Configuração Gerenciada pelo Gateway Unity na página Prévias . Consulte Gerenciar prévias do Databricks.

Use o gerenciamento de dispositivos móveis (MDM) e a CLI do Unity Gateway para distribuir a configuração do agente de codificação da sua equipe. Os administradores publicam a configuração no workspace, e os desenvolvedores usam seus agentes familiares com os modelos, servidores MCP e habilidades configurados.

Seu software MDM executa um script de provisionamento com privilégios de administrador em cada dispositivo. O script instala o ug, a CLI do Databricks e os agentes de codificação em toda a máquina e, em seguida, executa o ug configure, que instala a configuração do agente de codificação do workspace para todo o dispositivo. Os desenvolvedores então iniciam seu agente sem privilégios de administrador e fazem login com sua própria account do Databricks.

Implementar com o MDM

Configurar agentes de codificação

Habilite os agentes que sua equipe usa e publique a configuração em seu workspace. Consulte Configurar agentes de codificação.

Cada agente habilitado precisa de pelo menos um modelo na configuração que o service principal da próxima etapa possa usar. Por exemplo, o Claude Code precisa de modelos Claude. ug configure pula qualquer agente sem modelos.

Criar um service principal de provisionamento

A política MDM usa um Service Principal apenas para ler a configuração publicada durante a execução. Os desenvolvedores autenticam-se como eles mesmos.

Adicione uma Service Principal ao seu Workspace, por exemplo ug-mdm-provisioning.
Deixe apenas o direito de Acesso ao workspace habilitado. O service principal não precisa de outros direitos. Consulte Gerenciar direitos.
Conceda ao service principal acesso aos modelos, servidores MCP e habilidades na configuração publicada, incluindo os privilégios necessários do Unity Catalog. Consulte Conceder acesso a modelos, servidores MCP e habilidades.
Na tab Secrets da Service Principal, clique em Generate secret . Escolha um tempo de vida que corresponda à sua política de rotação. Em Scope , clique em Other APIs , adicione os escopos ai-gateway e unity-catalog e defina cada um como Read . Consulte O passo 1: Criar um segredo de OAuth.
Copie o ID do cliente e o segredo. Você não pode view o segredo novamente depois de fechar a caixa de diálogo.

Implantar com o software MDM

importante

Install ug in a shared location that every user on the device can run, not in the root user's home directory. ug configure records the path to ug in the machine-wide agent settings, and each developer's agent runs ug from that path to authenticate.

Jamf Pro (macOS)

Os passos implantam o Claude Code e o Codex em dispositivos macOS com o Jamf Pro. Cada dispositivo precisa de:

Acesso de rede à URL do seu workspace, PyPI (pypi.org e files.pythonhosted.org), GitHub (github.com e raw.githubusercontent.com), astral.sh e downloads.claude.ai.
Ferramentas de linha de comando para Xcode ou permissão para o script instalá-las com softwareupdate. ug é instalado a partir do GitHub, o que requer git.

Adicione o script

No Jamf Pro, vá para Settings > Gerenciamento de computador > Scripts > New e nomeie o script como Unity Gateway provision.
Na tab Script , cole o script a seguir:

view o script de provisionamento

Bash
#!/bin/bash
#
# macOS MDM provisioning script, written for Jamf Pro policies: install
# ug, the Databricks CLI, Claude Code and Codex machine-wide and run
# `ug configure` as root, which installs the workspace policy at
# /etc/unitygateway/managed-settings.json.
# Users then launch with no sudo:
#
#   UG_SKIP_OS_SETTINGS=1 ug claude    (or: ug codex)
#
# Jamf parameters ($1-$3 are reserved by Jamf):
#   $4  Databricks workspace URL, starting with https://
#   $5  Service principal OAuth client id
#   $6  Service principal OAuth client secret
#
# The token is used for this run only; developers sign in with their own
# OAuth. Needs access to PyPI, GitHub, astral.sh and downloads.claude.ai.

set -euo pipefail
umask 022
export HOME=/var/root
export PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
WORKSPACE="${4%/}"
PREFIX=/usr/local/unity-gateway
CLAUDE_RELEASES=https://downloads.claude.ai/claude-code-releases
CODEX_RELEASES=https://github.com/openai/codex/releases/latest/download
UG_REPO=https://github.com/databricks/unity-gateway
UV_URL=https://astral.sh/uv/install.sh
CLI_URL=https://raw.githubusercontent.com
CLI_URL="$CLI_URL/databricks/setup-cli/main/install.sh"
CLT_MARKER=/tmp/.com.apple.dt.CommandLineTools
CLT_MARKER="$CLT_MARKER.installondemand.in-progress"

# ug must be in a shared path: the machine-wide agent settings
# run it by absolute path for every user.
export UV_TOOL_DIR="$PREFIX/tools"
export UV_TOOL_BIN_DIR=/usr/local/bin
export UV_PYTHON_INSTALL_DIR="$PREFIX/python"
export UV_PYTHON_PREFERENCE=only-managed
mkdir -p /usr/local/bin

# Get ug from git
if ! xcode-select -p >/dev/null 2>&1; then
  touch "$CLT_MARKER"
  clt="$(softwareupdate -l 2>/dev/null \
    | sed -n 's/^\* Label: \(Command Line Tools.*\)$/\1/p' \
    | tail -n1)"
  softwareupdate -i "$clt"
  rm -f "$CLT_MARKER"
fi

if ! command -v uv >/dev/null; then
  curl -LsSf "$UV_URL" \
    | env UV_INSTALL_DIR=/usr/local/bin UV_NO_MODIFY_PATH=1 sh
fi
uv tool install --force "git+$UG_REPO"

if [ ! -x /usr/local/bin/databricks ]; then
  curl -fsSL "$CLI_URL" | sh
fi

# Download into a private temporary directory, not fixed /tmp paths
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT

# Install Claude Code
if [ ! -x /usr/local/bin/claude ]; then
  case "$(uname -m)" in
    arm64) platform=darwin-arm64 ;;
    *) platform=darwin-x64 ;;
  esac
  version="$(curl -fsSL "$CLAUDE_RELEASES/latest")"
  base="$CLAUDE_RELEASES/$version"
  checksum="$(curl -fsSL "$base/manifest.json" \
    | plutil -extract "platforms.$platform.checksum" raw -o - -)"
  curl -fsSL -o "$tmp/claude" "$base/$platform/claude"
  echo "$checksum  $tmp/claude" | shasum -a 256 -c -
  install -m 755 "$tmp/claude" /usr/local/bin/claude
fi

# Install Codex
if [ ! -x /usr/local/bin/codex ]; then
  case "$(uname -m)" in
    arm64) target=aarch64-apple-darwin ;;
    *) target=x86_64-apple-darwin ;;
  esac
  curl -fsSL "$CODEX_RELEASES/codex-$target.tar.gz" \
    | tar -xzf - -C "$tmp" "codex-$target"
  install -m 755 "$tmp/codex-$target" /usr/local/bin/codex
fi

# Get short lived credential; curl reads the client id and secret from
# stdin (-K -) so they don't appear in its arguments.
resp="$(printf 'user = "%s:%s"\n' "$5" "$6" \
  | curl -sS -K - \
      -d grant_type=client_credentials \
      --data-urlencode 'scope=ai-gateway:read unity-catalog:read' \
      "$WORKSPACE/oidc/v1/token")"
if ! DATABRICKS_BEARER="$(printf '%s' "$resp" \
    | plutil -extract access_token raw -o - -)"; then
  echo "Token request to $WORKSPACE failed: $resp" >&2
  exit 1
fi
export DATABRICKS_BEARER

ug configure --global --workspace "$WORKSPACE" \
  --agents claude,codex </dev/null

Na tab Opções , atribua o rótulo ao Parâmetro 4 como Workspace URL, o Parâmetro 5 como Client ID e o Parâmetro 6 como Client secret.
Clique em Salvar .

O script instala Claude Code, Codex e a CLI do Databricks apenas quando estão faltando e reinstala ug a cada execução. Ele não atualiza os agentes ou a CLI após a primeira instalação. Para mantê-los atualizados, modifique o script para corresponder à forma como você atualiza o software em seus dispositivos.

Criar a política

Vá para Computadores > Políticas > Novo .
Em Geral , defina Trigger para Check-in recorrente e Frequência de execução para Uma vez por dia . Cada dispositivo execução ug configure diariamente, o que aplica as atualizações de configuração que você publica no Workspace.
Em Scripts , adicione Unity Gateway provision com Priority definido como After . Insira os parâmetros:

Parâmetro	Valor
4 (URL do workspace)	O URL do seu workspace, começando com. `https://`
5 (ID do cliente)	O ID do cliente do Service Principal.
6 (Segredo do cliente)	O segredo da Service Principal.

Em Escopo , selecione os dispositivos para os quais direcionar. Comece com um pequeno grupo de dispositivos piloto.
Clique em Salvar . O Jamf Pro faz a execução da política em cada dispositivo de destino no próximo check-in.

atenção

Jamf Pro passes policy parameters to the script as command-line arguments. Any local user can read the client ID and secret, for example with ps, while the script runs, and Jamf Pro admins who can view the policy can read them too. The script doesn't write the credentials or the token to disk. To limit the impact of a leak, grant the service principal only the Workspace access entitlement, use a short secret lifetime, and rotate the secret regularly.

Iniciar agentes em máquinas de desenvolvedores

Depois que a política entra em execução em um dispositivo, os desenvolvedores iniciam seu agente a partir de um terminal sem privilégios de administrador:

Bash
UG_SKIP_OS_SETTINGS=1 ug claude
UG_SKIP_OS_SETTINGS=1 ug codex

UG_SKIP_OS_SETTINGS=1 diz ao ug para usar as configurações que a política de MDM instalou. Os desenvolvedores podem definir UG_SKIP_OS_SETTINGS=1 em seu perfil de shell para usá-lo em todas as sessões. O primeiro lançamento abre um navegador onde o desenvolvedor entra no Databricks. A atividade do agente de codificação é então atribuída ao desenvolvedor individual, não à Service Principal.

Para encurtar o comando de inicialização, dê aos desenvolvedores aliases que definem a variável e iniciam o agente, por exemplo, em um perfil de shell implantado com MDM:

Bash
alias claude='UG_SKIP_OS_SETTINGS=1 ug claude'
alias codex='UG_SKIP_OS_SETTINGS=1 ug codex'

Lançar o Claude para desktop

A mesma execução ug configure também configura o aplicativo de desktop Claude para cada usuário no dispositivo. Para dar suporte ao desktop do Claude, instale-o em seu script de provisionamento antes que o script entre em execução ug configure. O script do Jamf Pro acima não instala o desktop do Claude.

Quando um usuário abre o Claude desktop pela primeira vez, ele faz login com sua própria account Databricks. Os usuários também podem importar seus projetos e chats do claude.ai.

Verificar a implementação

Em um dispositivo piloto, entre com o account do sistema operacional do desenvolvedor e verifique se:

O agente é aberto e responde usando um modelo configurado.
Os servidores MCP e as competências configurados estão disponíveis e o desenvolvedor pode usá-los.
As solicitações aparecem no acompanhamento de uso do Unity Gateway e os rastreamentos aparecem se o rastreamento estiver ativado. Consulte Monitorar a atividade do agente de programação.

Repita essas verificações depois de alterar o script de provisionamento ou a configuração publicada.

Gerenciar credenciais e configuração

Para rotacionar o segredo do Service Principal:

Gere um novo segredo para o service principal.
Atualize o segredo na sua política de MDM.
Depois que a execução da política ocorrer em seus dispositivos, exclua o antigo secret.

Se o segredo for comprometido, gire-o imediatamente e exclua o segredo antigo. O token que o script solicita é de curta duração e o script não o grava no dispositivo, portanto, não há credencial por dispositivo para revogar.

Para atualizar a configuração, publique as alterações no workspace. Os dispositivos os aplicam na próxima vez que houver execução da política. Consulte Sincronizar atualizações de configuração.

Solução de problemas

Erro	Causa
`Token request to ... failed: {"error":"invalid_client"...}`	O ID ou segredo do cliente na política MDM está errado ou o segredo expirou.
`Token request ... failed: ... Scopes ... are not assigned to the client`	O secret não possui os escopos `ai-gateway:read` e `unity-catalog:read`.
`None of the coding agents enabled by your workspace configuration are available`	Nenhum agente habilitado tem modelos que o service principal possa usar, por exemplo, Claude Code configurado sem modelos Claude.

Erro	Causa
`Token request to ... failed: {"error":"invalid_client"...}`	O ID ou segredo do cliente na política MDM está errado ou o segredo expirou.
`Token request ... failed: ... Scopes ... are not assigned to the client`	O secret não possui os escopos `ai-gateway:read` e `unity-catalog:read`.
`None of the coding agents enabled by your workspace configuration are available`	Nenhum agente habilitado tem modelos que o service principal possa usar, por exemplo, Claude Code configurado sem modelos Claude.

Implementar com o MDM​

Configurar agentes de codificação​

Criar um service principal de provisionamento​

Implantar com o software MDM​

Adicione o script​

Criar a política​

Iniciar agentes em máquinas de desenvolvedores​

Lançar o Claude para desktop​

Verificar a implementação​

Gerenciar credenciais e configuração​

Solução de problemas​