Enterprise Deployments

This page covers everything needed to deploy Grok Build in enterprise environments, including network requirements, configuration management, authentication options, security controls, and the data lifecycle.

All connections use HTTPS (port 443).

These hosts are needed for core functionality:

If using enterprise OIDC, also allow your IdP's domain (e.g., login.microsoftonline.com).

These hosts support additional features and can be blocked without affecting core authentication and inference:

The x.ai and storage.googleapis.com hosts are only needed for the shell-script installer and in-app grok update. If your environment uses npm for distribution (npm install -g @xai-official/grok), neither host is required.

All connections use TLS 1.2 or TLS 1.3, enforced by rustls (no OpenSSL dependency). Root certificates are loaded from the OS trust store. There is no option to disable TLS. For TLS-inspecting proxies, install the proxy's CA certificate into the OS trust store.

The CLI honors standard proxy environment variables (HTTPS_PROXY, HTTP_PROXY, NO_PROXY). The HTTP connection pool keeps idle connections open for 90 seconds by default (GROK_POOL_IDLE_TIMEOUT_SECS), and inference requests use SSE streaming where the per-chunk idle timeout defaults to 600 seconds. Set proxy idle timeouts to at least 10 minutes to avoid premature disconnects during long model responses.

Grok loads configuration from five layers, lowest to highest priority:

Settings in requirements.toml cannot be overridden by lower layers, remote settings, or user config — use it for compliance-critical policies. All layers support [[version_overrides]] for version-conditional patches and $VAR expansion.

The highest-priority configuration layer is /etc/grok/requirements.toml. This is the recommended mechanism for organizations managing Grok at scale via Mobile Device Management (MDM), golden images, configuration management tools, or onboarding scripts.

Common deployment patterns:

• MDM / endpoint management — Push the TOML files directly into /etc/grok/ on managed workstations.
• Golden images / AMIs — Bake the policy files into base images used for developer laptops or CI runners.

Values pinned in requirements.toml use a fail-closed "pin" mechanism: they cannot be overridden by user config.toml, environment variables, remote settings, or lower-priority layers. This makes /etc/grok/requirements.toml the authoritative source for compliance-critical policies such as disabling telemetry, enforcing sandbox profiles, restricting tools, or pinning specific feature flags.

Organizations that already use Claude Code and have deployed its managed-settings.json file via MDM can continue to rely on that file. Grok reads a subset of policies from it (permission rules, MCP server allowlists, a few telemetry/feedback flags, and marketplace restrictions) for compatibility.

Grok's own /etc/grok/requirements.toml always takes precedence over the Claude managed-settings.json file. The Claude compatibility layer is only relevant for mixed Claude + Grok environments; pure Grok deployments should use requirements.toml + config.toml.

Grok Build supports four session authentication methods:

When multiple credentials are available, Grok resolves them per model: model.api_key > model.env_key > active session token > XAI_API_KEY.

Organizations with a corporate identity provider (Entra ID, Okta, Auth0, etc.) can configure Grok to authenticate directly against it:

[auth.oidc]
issuer = "https://login.yourcompany.com"
client_id = "your-client-id"

Or via environment: GROK_OIDC_ISSUER and GROK_OIDC_CLIENT_ID. The flow uses PKCE and supports refresh_token grants for automatic renewal.

Point Grok at an executable that produces a token on stdout:

[auth]
auth_provider_command = "/usr/local/bin/your-auth-provider"

The command must print either a bare token string or JSON: {"access_token": "...", "refresh_token": "...", "expires_in": 3600} (refresh_token and expires_in are optional). When the token expires, Grok re-runs the command with GROK_AUTH_EXPIRED=1 set. Interactive login allows up to 300 seconds for the command to complete. Background token refresh uses a 10-second timeout; if the command hangs (e.g., waiting for interactive input), Grok kills it and reports the failure.

For CI/CD and headless automation, set the XAI_API_KEY environment variable — no config file needed:

export XAI_API_KEY="xai-..."
grok -p "Review this diff" --output-format json --always-approve

On persistent developer workstations, you can instead bind a key to a specific model in ~/.grok/config.toml:

[model.grok-build]
api_key = "xai-..."

[models]
default = "grok-build"

See Headless & Scripting for output formats and CLI flags.

For environments without a browser (SSH, containers, cloud devboxes), device code login follows RFC 8628:

grok login --device-auth

Grok prints a URL and a short user code. Complete login on any device with a browser.

The sandbox is applied once at process startup and is irreversible. It uses Landlock on Linux (kernel 5.13+) and Seatbelt on macOS.

Set the profile with --sandbox workspace or pin it in requirements.toml under [sandbox] profile.

Certain directories are always write-protected regardless of profile: ~/.ssh, ~/.gnupg, ~/.grok/auth, ~/.aws, ~/.config/gcloud, ~/.azure.

In read-only and strict profiles, child processes are blocked from making network connections via a seccomp BPF filter. This enforcement is Linux-only; on macOS, child network blocking is not currently enforced.

Custom profiles can be defined in ~/.grok/sandbox.toml or .grok/sandbox.toml:

[profiles.my-profile]
extends = "workspace"
restrict_network = true
deny = ["/secrets"]

The permission system controls which tool calls the model can execute, independent of the sandbox. When the model requests a tool, checks run in order: PreToolUse hooks, policy rules (deny > ask > allow), built-in fast paths, then the prompt policy. See Modes and Commands for the basic ask and always-approve modes.

For enterprise and CI environments, two additional modes are relevant:

Set via --permission-mode in headless mode (e.g., grok -p "..." --permission-mode dontAsk; accepts default, dontAsk, acceptEdits, bypassPermissions, plan) or [ui] permission_mode in config for persistent use (accepts ask, always-approve).

Always-safe operations

Certain read-only operations are auto-approved without prompting in all modes, including dontAsk: read_file, list_dir, grep, web_search, todo_write, and a curated set of safe shell commands including ls, cat, pwd, date, whoami, hostname, uptime, ps, head, tail, wc, sort, uniq, tr, cut, grep, git status, git branch, git log, git diff, git ls-files, git show, git rev-parse, cargo check, and kubectl get/logs/describe. Shell commands are parsed per-segment — ls && rm -rf / will auto-approve ls but block rm.

Policy rules

Fine-grained allow/deny rules target specific tool types with glob patterns. Deny rules always take precedence over allow rules.

grok -p "Review the API changes" \
  --permission-mode dontAsk \
  --allow 'Bash(git *)' \
  --allow 'Bash(gh *)' \
  --allow 'Read' \
  --allow 'Grep' \
  --deny 'Bash(rm -rf *)'

Supported tool filters: Bash, Edit, Read, Grep, MCPTool, WebFetch. Rule syntax: Bash(git *) matches any command starting with git; Edit(**/*.rs) matches Rust files; MCPTool(my-server__*) matches MCP tools from a specific server.

Rules can also be set in ~/.grok/config.toml:

[permission]
rules = [
  { action = "allow", tool = "bash", pattern = "git *" },
  { action = "allow", tool = "read" },
  { action = "deny",  tool = "bash", pattern = "*" },
]

Dangerous commands

rm, chmod, chown, chgrp, chattr, kill, pkill, killall, and git push always prompt in ask mode, even if the user has whitelisted them. In always-approve mode, they are auto-approved like all other commands. To block them in always-approve mode, add explicit deny rules.

Combining permissions with sandbox

Permissions control what the model is allowed to request. The sandbox controls what the process can do even if a command is approved. For untrusted code, combine dontAsk + narrow allow rules + --sandbox strict.

A session moves data through six phases:

1. User input — prompt and file content assembled locally.
2. Transport — sent over TLS 1.2/1.3 to the inference proxy.
3. Inference — the proxy forwards to the model. ZDR organizations route through a dedicated service identity that skips logging.
4. Tool execution — happens locally in the user's sandboxed environment.
5. Response — streams back over the same TLS connection.
6. Session end — no prompts, code, or responses are persisted at the inference layer for ZDR organizations. Local session history is stored in ~/.grok/.

ZDR is enforced at the team level. When enabled for a team or enterprise, zero data retention occurs when using Grok Build.