Last updated on

How to Install and Use Grok Build, the Open-Source grok CLI

Takeaway: Grok Build installs with one command and signs you in through the browser. Before you point it at a real repository, start it with grok --sandbox workspace and add a short allow/deny rule list, because the sandbox is off by default and the built-in profiles do not protect ~/.ssh. This guide covers those safety settings, plus MCP servers, a custom model, headless runs for CI, and editor use over ACP.

Read time: ~9 minutes. Key facts:

  • Grok Build is xAI’s terminal coding agent, the grok command. Its Rust source is on GitHub under Apache 2.0.
  • Install: curl -fsSL https://x.ai/cli/install.sh | bash, then grok --version.
  • You can run it three ways: as an interactive TUI, headless with grok -p for scripts and CI, or inside an editor over the Agent Client Protocol with grok agent stdio.
  • The sandbox is off by default. Five profiles are built in: off, workspace, devbox, read-only and strict. Landlock enforces them on Linux and Seatbelt on macOS.
  • Permission rules in ~/.grok/config.toml allow or deny tools by pattern. Deny always wins.

Sourcing note: commands, flags, config keys and sandbox behavior are quoted from xAI’s Grok Build docs and the xai-org/grok-build README. I re-checked them on October 23, 2026. Grok Build updates itself often, so check the changelog when a flag behaves differently. Links at the bottom.

xAI open-sourced Grok Build in July 2026. That came days after users found the CLI uploading whole working directories to xAI’s cloud storage; our news write-up covers that incident and the release. This guide is the hands-on path: install, sign in, lock it down, then put it to work. The flag-by-flag reference, version pinning and slash commands are in the companion Grok Build CLI handbook.

1. Install it

xAI publishes prebuilt binaries for macOS, Linux and Windows:

# macOS / Linux / Git Bash
curl -fsSL https://x.ai/cli/install.sh | bash

# Windows PowerShell
irm https://x.ai/cli/install.ps1 | iex

# verify
grok --version

The build artifact is called xai-grok-pager, and the installer puts it on your PATH as grok. Running curl … | bash executes whatever the URL returns. If you would rather read the script first, download install.sh, read it, then run it.

2. Sign in and run a first session

Start from the project you want it to work on:

cd your-project
grok

On first launch, grok opens a browser so you can sign in. On a server or anywhere else without a browser, set an API key and start it again:

export XAI_API_KEY="xai-..."   # placeholder from the docs, not a real key
grok

The overview suggests two first prompts that are good for getting your bearings: Explain this repo. and @src/main.rs Walk me through this file. (@path attaches a file.)

Next, check what the agent actually loaded in this directory:

grok inspect

grok inspect lists the config sources it resolved and the instructions, skills, plugins, hooks and MCP servers it found. Run it in each new repo. It is the quickest way to spot an MCP server or hook you did not expect. (overview)

3. Turn on the sandbox before a real repo

The sandbox limits where the agent’s tools can write and, on Linux, whether the processes it starts can reach the network. It is off by default. These are the built-in profiles:

ProfileReadWriteNetwork for child processes
offanywhereanywhereallowed
workspaceanywherecurrent directory, ~/.grok/, tempallowed
devboxanywheretop-level dirs except /dataallowed
read-onlyanywhere~/.grok/ and temp onlyblocked
strictcurrent directory and system pathscurrent directory, ~/.grok/, tempblocked

You can turn it on three ways:

grok --sandbox workspace            # one session
export GROK_SANDBOX=workspace       # this shell
# ~/.grok/config.toml — every session
[sandbox]
profile = "workspace"

Three details from the sandbox docs matter in practice:

  • None of the built-in profiles protect ~/.ssh, and workspace still lets the agent read anywhere. To keep secrets out of reach, add a custom profile with a deny list.
  • Network blocking for child processes works only on Linux. On macOS, read-only and strict do not block the network.
  • Calls to the model API and the web tools are not blocked by the child-network setting, because the agent needs them to work.

You can define a custom profile in ~/.grok/sandbox.toml, or per project in .grok/sandbox.toml:

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

Then run grok --sandbox my-profile. If you want an extra layer, such as default-deny network rules, run the whole agent inside an outer sandbox. Our OpenShell guide shows one way.

4. Set permission rules instead of approving everything

The default mode is Ask: you approve each tool call. Auto uses a classifier to decide. Always-approve (/always-approve, Ctrl+O, or --always-approve) skips the prompts entirely. Shift+Tab cycles through Normal → Plan → Auto → Always-approve. To set a default, put [ui] permission_mode = "auto" (or "ask" or "always-approve") in your user config. That key is read from user config only.

Rules let you skip prompts for safe commands and block dangerous ones:

# ~/.grok/config.toml
[permission]
rules = [
  { action = "allow", tool = "bash", pattern = "git *" },
  { action = "allow", tool = "read" },
  { action = "deny",  tool = "bash", pattern = "rm -rf *" },
]

For a single run, --allow and --deny take the same kind of rule on the command line. Deny always beats allow. Even with a remembered grant, dangerous patterns such as rm and git push still prompt you. (permissions docs)

The pattern is the same as in Claude Code, where allow/ask/deny rules and auto mode work much the same way; see our Claude Code permissions guide.

5. Add MCP servers

# a local stdio server
grok mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir

# a remote HTTP server
grok mcp add --transport http linear https://mcp.linear.app/mcp

grok mcp list
grok mcp doctor filesystem      # add --json for machine-readable output
grok mcp remove filesystem

By default grok mcp add writes to your user config. Add --scope project to write .grok/config.toml in the repo instead, so the whole team gets the same servers. If a project server has the same name as one in your user config, the project one replaces it. Tools show up as <server>__<tool>, and OAuth tokens for remote servers are stored in ~/.grok/mcp_credentials.json.

One thing to check: Grok also loads MCP servers from ~/.claude.json, .cursor/mcp.json and .mcp.json. If grok inspect lists servers you never added to Grok, they came from there. To turn that off, add [compat.claude] mcps = false. (MCP docs)

Every MCP tool also adds to the context the model reads. Our Claude Code token-overhead guide shows how to measure that cost, and the same approach works here.

6. Use a different model

To pick the model for one session, use -m, or /model inside the TUI. To add an OpenAI-compatible endpoint of your own, define it in ~/.grok/config.toml:

[model.my-model]
model = "model-id"
base_url = "https://api.example.com/v1"
name = "Display Name"
env_key = "API_KEY"

[models]
default = "my-model"

Check it with grok inspect, then send a test prompt: grok -p "Hello" -m my-model. When you compare runs, fix the model explicitly. Grok 4.7 arrived in Grok Build 1.0.40 (our note), and sessions that didn’t set a model may not have used the same one.

7. Run it headless in scripts and CI

grok -p "List TODO comments" --output-format json
grok --no-auto-update -p "Summarize the last 5 commits" --output-format streaming-json

These are the flags you will use most: -p/--single (one prompt), -m/--model, --cwd <PATH>, --output-format plain|json|streaming-json, -s/--session-id <ID> (create or resume a named session), -r/--resume <ID>, -c/--continue (the most recent session in this directory), and --no-alt-screen (run inline instead of fullscreen). Sessions are stored in ~/.grok/sessions.

In CI, use --no-auto-update or set [cli] auto_update = false, so the version doesn’t change between runs. Use --always-approve only inside a throwaway container. On a machine with real credentials, use --sandbox together with --allow/--deny. The handbook has the full flag table, including --max-turns.

8. Use it from an editor (ACP)

grok agent stdio speaks the Agent Client Protocol (JSON-RPC over stdio), and editors that support ACP launch it as their agent. It authenticates with either XAI_API_KEY (xai.api_key) or the token cached by an earlier grok login (cached_token). The docs’ sample ACP client fails with “Run grok login first, or set XAI_API_KEY.” when neither is available. If your editor can’t start the agent, run grok login or set the key in a terminal, then restart the editor’s agent.

9. Build from source (optional)

cargo install dotslash
/usr/bin/env dotslash --help          # sanity check
cargo check -p xai-grok-pager-bin     # fast validation
cargo run -p xai-grok-pager-bin       # build + launch the TUI
cargo build -p xai-grok-pager-bin --release   # → target/release/xai-grok-pager

The Rust toolchain version is pinned in rust-toolchain.toml. protoc comes from the DotSlash wrapper; if that isn’t available, the build uses $PROTOC or whatever is on your PATH. macOS and Linux are the supported build hosts, and Windows is best-effort. The root Cargo.toml is generated, so edit the per-crate files instead. xAI does not accept external contributions: you can read, build and fork the repo, but don’t open pull requests.

Troubleshooting

grok isn’t found after install. Open a new shell so PATH reloads, or run the installer from section 1 again. Then run grok --version.

There is no browser to sign in with. Run grok login --device-auth, which uses a device code for remote or headless machines, or set XAI_API_KEY and run grok again. Don’t commit the key. In CI, store it as a secret.

The agent edited a file outside the repo. You were running with the sandbox off, which is the default. Use --sandbox workspace or set [sandbox] profile, then run grok inspect to confirm the profile is active.

npm install fails under read-only or strict on Linux. That is the child-network block working. Install dependencies before you start the session, or switch to workspace for that task.

strict didn’t block the network on a Mac. That’s expected. Child-network blocking is enforced only on Linux.

MCP servers you never added show up. Grok also reads ~/.claude.json, .cursor/mcp.json and .mcp.json. Set [compat.claude] mcps = false to turn that off.

An MCP server times out at startup. A cold npx download can take more than the default 30 seconds. Raise startup_timeout_sec for that server, and read ~/.grok/logs/mcp/<server>.stderr.log. grok mcp doctor <name> runs the checks for you.

A CI job behaves differently from one day to the next. The CLI may have updated itself, or the default model may have changed. Use --no-auto-update and pass -m explicitly.

rm or git push still asks for approval after you chose “always allow”. That’s by design: dangerous patterns prompt even with a remembered grant. In a disposable environment, use a deny/allow rule list or --always-approve.

FAQ

Is Grok Build free? The CLI is open source (Apache 2.0). Model usage is billed to your xAI account, either through the browser sign-in or through XAI_API_KEY on the xAI API.

Does it still upload my working directory? According to the reporting in our news write-up, xAI disabled the upload after the July incident. Because the code is public, you can check this yourself. Either way, the sandbox and deny list above limit what the agent can reach.

How does it differ from the Claude Code or Codex CLI? The workflow is much the same: a TUI, headless mode, MCP, permission rules. The practical differences are that the whole Rust source is readable, the sandbox profiles are built in, and it can reuse the MCP config files you already have.

Where is the full flag list? Run grok --help, or see our Grok Build CLI handbook.

Sources

  • xai-org/grok-build — GitHub: Apache 2.0 Rust source, install commands, binary name, build from source (cargo check -p xai-grok-pager-bin, DotSlash sanity check, protoc fallback), no external contributions, changelog link.
  • Grok Build overview: first launch, XAI_API_KEY, first prompts, grok -p, grok inspect, ~/.grok/config.toml.
  • Sandbox: profiles table, Landlock/Seatbelt, Linux-only child-network blocking, ~/.ssh not protected, custom sandbox.toml profiles.
  • Permissions: Ask/Auto/Always-approve, [permission] rules, --allow/--deny, deny wins, dangerous patterns re-prompt.
  • MCP servers: grok mcp add/list/remove/doctor, --scope project, tool namespacing, credentials file, Claude/Cursor config compatibility, stderr logs, startup_timeout_sec.
  • Headless scripting and CLI reference: flags, sessions, --no-auto-update, grok agent stdio (ACP) and its auth methods.
  • Settings: custom [model.*] entries and [models] default.
  • Grok Build changelog.
  • First published July 18, 2026. Re-verified and expanded October 23, 2026.