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.

Two policies control how users authenticate. Set them in requirements.toml so a user config.toml, an environment variable, or a remote setting cannot override them.

disable_api_key_auth forces interactive IdP login. The xai.api_key method is no longer offered or accepted, and at request time a first-party xAI API key is replaced with the IdP session token, so a leftover XAI_API_KEY or per-model key cannot skip SSO. Third-party (BYOK) endpoints keep working, since their base_url is not on x.ai; restrict those through your own provider IAM.

[grok_com_config]
disable_api_key_auth = true

force_login_team_uuid pins login to a team. The token's team principal must match the configured value, so a personal login or a login to the wrong team is rejected with an error and nothing is written to auth.json. You can set a single team UUID or a list, in which case any team in the list is allowed; an empty list rejects every login. Setting this also turns on disable_api_key_auth, because a bare API key does not carry team membership.

[grok_com_config]
force_login_team_uuid = "<your-team-uuid>"
# Or allow several teams:
# force_login_team_uuid = ["<team-a-uuid>", "<team-b-uuid>"]

The value is the team's UUID, which the access token carries as its login principal. Enforcement applies every time a session is issued or reused, including cached tokens and silent refreshes. A session that no longer complies is cleared, so the user has to log in again. Run grok inspect to check which login policy loaded.

If you are migrating from Claude Code, forceLoginMethod maps to disable_api_key_auth, and forceLoginOrgUUID maps to force_login_team_uuid, which takes team UUIDs.

Day-to-day permissions (modes, allow/deny rules) and sandbox profiles apply to individual machines as well as managed deployments. This section covers enterprise-only policy: pinning, headless modes, and locking always-approve off.

Profiles, custom sandbox.toml, and how the sandbox relates to permissions are under Sandbox. Pin a profile in requirements.toml:

[sandbox]
profile = "workspace"

Ask, auto, and always-approve, plus CLI --allow / --deny and config rules, are under Permissions. For CI and headless runs, two additional modes matter:

Example headless run:

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

Locking bypass-permissions mode

Set disable_bypass_permissions_mode = true under [ui] to turn always-approve (bypass-permissions) off across the deployment. This blocks every way to switch it back on: the --yolo and --permission-mode bypassPermissions flags, the in-session toggles (Ctrl+O, /always-approve, and the Shift+Tab mode cycle), client-supplied yolo settings, and catch-all allow rules such as * or **. Deny rules still apply, and behavior is unchanged when no lock is set.

[ui]
disable_bypass_permissions_mode = true

To resist tampering, the lock is honored only from root-owned sources (/etc/grok/requirements.toml or the system layer), not from the user-writable ~/.grok/requirements.toml. Claude Code's managed-settings.json disableBypassPermissionsMode: "disable" is not applied to grok's always-approve — grok honors that file's permission rules, MCP allowlists, and marketplace restrictions, but a developer's --yolo / [ui] permission_mode / runtime toggle still take effect. This keeps grok from inheriting a host's Claude Code lockdown (e.g. shared clusters hardened by AppSec); to disable always-approve in grok, set disable_bypass_permissions_mode = true in grok's own requirements.toml.

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.