53 53
54Settings 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.54Settings 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.
55 55
56### System-level policy for MDM and fleet deployments56### System-level policy for MDM and managed deployments
57 57
58The 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.58The 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.
59 59
163 163
164## Security controls164## Security controls
165 165
166### Sandbox166Day-to-day [permissions](/build/features/permissions) (modes, allow/deny rules) and [sandbox](/build/features/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.
167
168The sandbox is applied once at process startup and is irreversible. It uses Landlock on Linux (kernel 5.13+) and Seatbelt on macOS.
169
170| Profile | Filesystem read | Filesystem write | Child network | Use case |
171| --- | --- | --- | --- | --- |
172| `off` | Unrestricted | Unrestricted | Allowed | No sandbox (default) |
173| `workspace` | Everywhere | CWD, `/tmp`, `~/.grok/` | Allowed | Normal development |
174| `devbox` | Everywhere | Everything except `/data` | Allowed | Cloud devbox environments |
175| `read-only` | Everywhere | `~/.grok/` and tmp only | Blocked | Code review, auditing |
176| `strict` | CWD and system paths only | CWD, `/tmp`, `~/.grok/` | Blocked | Untrusted repositories |
177
178Set the profile with `--sandbox workspace` or pin it in `requirements.toml` under `[sandbox] profile`.
179
180Certain directories are always write-protected regardless of profile: `~/.ssh`, `~/.gnupg`, `~/.grok/auth`, `~/.aws`, `~/.config/gcloud`, `~/.azure`.
181 167
182In `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.168### Sandbox
183 169
184Custom profiles can be defined in `~/.grok/sandbox.toml` or `.grok/sandbox.toml`:170Profiles, custom `sandbox.toml`, and how the sandbox relates to permissions are under [Sandbox](/build/features/sandbox). Pin a profile in `requirements.toml`:
185 171
186```text172```text
187[profiles.my-profile]173[sandbox]
188extends = "workspace"174profile = "workspace"
189restrict_network = true
190deny = ["/secrets"]
191```175```
192 176
193### Permissions177### Permissions
194 178
195The 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.179Ask, auto, and always-approve, plus CLI `--allow` / `--deny` and config rules, are under [Permissions](/build/features/permissions). For CI and headless runs, two additional modes matter:
196
197For enterprise and CI environments, two additional modes are relevant:
198 180
199| Mode | Behavior | Typical use |181| Mode | Behavior | Typical use |
200| --- | --- | --- |182| --- | --- | --- |
201| `dontAsk` | Silently deny anything without an explicit allow rule | Headless, CI, high-security |183| `dontAsk` | Silently deny anything without an explicit allow rule | Headless, CI |
202| `acceptEdits` | Auto-approve file edits; prompt for shell commands | Semi-automated workflows |184| `acceptEdits` | Auto-approve file edits; prompt for shell commands | Semi-automated workflows |
203 185
204Set 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`).186Example headless run:
205
206**Always-safe operations**
207
208Certain 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`.
209
210**Policy rules**
211
212Fine-grained allow/deny rules target specific tool types with glob patterns. Deny rules always take precedence over allow rules.
213 187
214```bash customLanguage="bash"188```bash customLanguage="bash"
215grok -p "Review the API changes" \189grok -p "Review the API changes" \
218 --allow 'Bash(gh *)' \192 --allow 'Bash(gh *)' \
219 --allow 'Read' \193 --allow 'Read' \
220 --allow 'Grep' \194 --allow 'Grep' \
221 --deny 'Bash(rm -rf *)'195 --deny 'Bash(rm -rf *)' \
222```196 --sandbox strict
223
224Supported 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.
225
226Rules can also be set in `~/.grok/config.toml`:
227
228```text
229[permission]
230rules = [
231 { action = "allow", tool = "bash", pattern = "git *" },
232 { action = "allow", tool = "read" },
233 { action = "deny", tool = "bash", pattern = "*" },
234]
235```197```
236 198
237**Dangerous commands**
238
239`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.
240
241**Combining permissions with sandbox**
242
243Permissions 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`.
244
245**Locking bypass-permissions mode**199**Locking bypass-permissions mode**
246 200
247Set `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.201Set `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.
