Grok Build · Sandbox Profiles

Five Sandbox Profiles

workspace, devbox, read-only, strict, and off define different capability sets for the filesystem and subprocess networking. Names give direction; the actual boundaries require examining the resolved capability set.

Learning Objective

Be able to infer read/write and network boundaries from ProfileName and SandboxProfile, correctly configure custom extends, and identify platform support and degradation conditions.

TEACHING DIAGRAM

Profiles Are Multi-Dimensional Capability Presets

Horizontal position aids memory. The actual differences between devbox, workspace, and strict simultaneously involve default reads, writable paths, and network policy.

Teaching capability spectrum of the five profiles offno sandbox devboxbroad writes workspacedefault profile strictallowlisted reads read-onlyno workspace write More openMore restrictive
Source-Level Semantics of the Five Built-in Profiles
workspace

Full filesystem readable by default; workspace, GROK_HOME, and temp directories writable; no subprocess network restriction.

default_read=true
restrict_network=false
devbox

Full filesystem readable by default; enumerates root directories, granting broad write permissions except /data and virtual filesystems; no network restriction.

/data remains readable; write-protected on Linux via bwrap
read-only

Full filesystem readable by default; workspace not writable; GROK_HOME, temp directories, and required devices remain writable.

restrict_network=true
strict

Global default read disabled; only system runtime directories and workspace are open; workspace, GROK_HOME, and temp directories remain writable.

default_read=false
restrict_network=true
off

Skips capability set application and logs "Sandbox disabled." Also accepts the alias none.

Cannot be used as a base for custom extends
Two common misreadings: workspace still allows reading files outside the workspace; strict still allows writing to workspace. read-only also preserves the minimum writable directories needed to run. Profile names must defer to source-code capabilities — not be completed by their literal meaning.
Custom Profiles & Configuration Boundaries

extends Rules

  • custom starts from workspace by default.
  • Can extend workspace, devbox, read-only, or strict.
  • Cannot extend off/none.
  • Cannot extend another custom profile.
  • read_only, read_write, deny are appended to the base class. When subprocess network restriction is needed, explicitly set restrict_network=true in the custom profile.

Global Priority Protection

The system reads ~/.grok/sandbox.toml first, then .grok/sandbox.toml. Project configuration can only add new profile names. If a project declares a profile with the same name as an existing global profile, merge uses entry.or_insert, keeping the global definition in effect.

crates/codegen/xai-grok-sandbox/src/profiles.rs crates/codegen/xai-grok-sandbox/src/paths.rs ProfileName load_sandbox_config merge_project_profiles
Platform Mechanisms & Degradation Conditions

Filesystem Constraints

When enforce is enabled and running on Unix, capabilities are applied via Landlock or Seatbelt. macOS deny uses Seatbelt rules; Linux sub-path read-deny also requires bwrap bind-over.

Network Constraints

The main process network remains open to access model APIs. restrict_network is currently expressed through subprocess filtering; the seccomp implementation in source code is effective on Linux, while non-Linux functions are no-ops. Platform boundaries must be verified against actual build and runtime environments.

Avoid absolutes: If the platform is unsupported, enforce is not enabled in the build, or apply fails, the source code logs a warning and continues running. is_active() reflects whether it was actually applied. Therefore, no guarantee can be made that all environments are "impossible to bypass."
Real Source Code Snapshot
crates/codegen/xai-grok-sandbox/src/profiles.rsREAL SOURCE
pub enum ProfileName {
    #[default]
    Workspace,
    Devbox,
    ReadOnly,
    Strict,
    Off,
    Custom(String),
}

Snapshot note: The enum is fully preserved. The spectrum diagram aids teaching memory; actual capabilities come from resolve(), essential_writable_paths(), and platform apply results.

Classroom Exercise: Design a Review-Only Profile

Requirements: read access to repository and system tools, no workspace write, allow write to temp directories, restrict subprocess networking, and additionally deny ~/.ssh. Choose a built-in base class, write the extends and deny for the custom profile, and explain why a project cannot replace a user-global definition with the same name.

Takeaway: The five profiles are parseable capability templates. Evaluating security requires examining default read, writable paths, deny, subprocess networking, platform support, and apply status; custom merge rules prevent projects from silently weakening a same-named global policy.