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

## Network requirements

All connections use HTTPS (port 443).

### Required

These hosts are needed for core functionality:

| Host | Purpose |
| --- | --- |
| `cli-chat-proxy.grok.com` | Inference proxy, settings |
| `auth.x.ai` | OAuth2/OIDC authentication |

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

### Additional

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

| Host | Purpose | Impact if blocked |
| --- | --- | --- |
| `api.x.ai` | xAI API (direct API-key path) | Only needed when using `api_key` auth instead of the inference proxy |
| `code.grok.com` | Remote session sync, sharing, WebSocket relay | Sessions stay local-only; share links unavailable |
| `assets.grok.com` | Profile images, UI assets | User avatars won't load; no functional impact |
| `x.ai` | CLI binary downloads via `curl \| bash` install script | Use `npm install -g @xai-official/grok` as an alternative that doesn't require this host |
| `storage.googleapis.com` | Fallback CDN for CLI binaries | Only needed if `x.ai` is unreachable during `curl \| bash` install |

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.

### TLS

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.

### Proxy support

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.

## Configuration

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

| Priority | Source | Purpose |
| --- | --- | --- |
| 1 (lowest) | `/etc/grok/managed_config.toml` | System-wide managed config |
| 2 | `~/.grok/managed_config.toml` | Per-user managed config |
| 3 | `~/.grok/config.toml` | User preferences |
| 4 | `~/.grok/requirements.toml` | User-level pinned settings |
| 5 (highest) | `/etc/grok/requirements.toml` | System-level pinned settings |

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.

### System-level policy for MDM and fleet deployments

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.

### Claude Code compatibility (optional)

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

## Authentication

Grok Build supports four session authentication methods:

| Method | Trigger | Refreshable | Best for |
| --- | --- | --- | --- |
| Browser OIDC | `grok login` (default) | Yes | Interactive terminals with a browser |
| Device code | `grok login --device-auth` | Yes | SSH sessions, containers, headless hosts |
| External auth provider | `auth_provider_command` in config | Yes | Corporate IdPs, custom token brokers |
| API key | `XAI_API_KEY` env var or `model.api_key` in config | No | Scripts, CI/CD, headless automation |

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

### Enterprise OIDC

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

```text
[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.

### External auth provider

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

```text
[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.

### API key

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

```bash customLanguage="bash"
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`:

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

[models]
default = "grok-build"
```

See [Headless & Scripting](/build/cli/headless-scripting) for output formats and CLI flags.

### Device code

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

```bash customLanguage="bash"
grok login --device-auth
```

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

## Security controls

### Sandbox

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

| Profile | Filesystem read | Filesystem write | Child network | Use case |
| --- | --- | --- | --- | --- |
| `off` | Unrestricted | Unrestricted | Allowed | No sandbox (default) |
| `workspace` | Everywhere | CWD, `/tmp`, `~/.grok/` | Allowed | Normal development |
| `devbox` | Everywhere | Everything except `/data` | Allowed | Cloud devbox environments |
| `read-only` | Everywhere | `~/.grok/` and tmp only | Blocked | Code review, auditing |
| `strict` | CWD and system paths only | CWD, `/tmp`, `~/.grok/` | Blocked | Untrusted repositories |

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`:

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

### Permissions

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](/build/modes-and-commands) for the basic `ask` and `always-approve` modes.

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

| Mode | Behavior | Typical use |
| --- | --- | --- |
| `dontAsk` | Silently deny anything without an explicit allow rule | Headless, CI, high-security |
| `acceptEdits` | Auto-approve file edits; prompt for shell commands | Semi-automated workflows |

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.

```bash customLanguage="bash"
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`:

```text
[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`.

## Privacy & data lifecycle

### Data lifecycle

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/`.

### Zero Data Retention

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