Grok Build Getting Started Guide: Install, Configure, and Use the AI Coding Agent

A beginner-friendly guide to Grok Build, xAI's coding agent. Learn how to install it, run interactive and headless sessions, configure custom models, manage plugins and skills, and deploy it in enterprise environments.

You open a new project, and you have no idea where to begin. The codebase is unfamiliar, the docs are scattered, and you just want something to explain what's going on and help you move fast. That's exactly the kind of problem Grok Build was made for.

Grok Build is a coding agent from xAI that you can run as a full interactive terminal UI, fire off as a one-liner in a script, or plug into your own tools via a standard protocol. It reads your project, understands the context, and helps you write, review, and refactor code.

This guide walks you through everything from first install to enterprise deployment, with practical examples at every step.

---

How to Install Grok Build

macOS / Linux:

curl -fsSL https://x.ai/cli/install.sh | bash

Windows (PowerShell):

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

Once installed, navigate to your project and start Grok:

cd your-project
grok

On first launch, it opens a browser for authentication. If you are in a headless environment like a server or container, use an API key instead:

export XAI_API_KEY="xai-..."
grok

Some useful first prompts to try inside the TUI:

Explain this repo.
@src/main.rs Walk me through this file.

---

Running Grok Without the TUI (Headless Mode)

Headless mode is great for scripts, CI pipelines, and automations. You skip the interactive UI entirely.

grok -p "Explain this codebase"
grok -p "Explain the architecture" --output-format streaming-json

Common headless flags:

Flag	What it does
-p, --single <PROMPT>	Send a single prompt
-m, --model <MODEL>	Choose a specific model
-s, --session-id <ID>	Create or resume a named session
-r, --resume <ID>	Resume an existing session
-c, --continue	Continue the most recent session
--cwd <PATH>	Set the working directory
--output-format <FMT>	Choose plain, json, or streaming-json
--always-approve	Auto-approve all tool calls
--no-alt-screen	Run inline without fullscreen takeover

Output format options:

• plain: Human-readable text
• json: One JSON object at the end
• streaming-json: Newline-delimited JSON events as they arrive

In automated environments, add --no-auto-update to skip background update checks:

grok --no-auto-update -p "Review this diff" --output-format json

---

Using Custom Models

Grok supports any custom model. Add it to your config file at ~/.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"

Then verify what Grok sees in your project and run with your custom model:

grok inspect
grok -p "Hello" -m my-model

You can also switch models mid-session in the TUI with /model <name>.

---

Using the grok-build-0.1 Model via API

The same model powering Grok Build is available directly through the xAI API. You can drop it into your own tooling.

curl:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-build-0.1",
    "input": "Refactor this function to handle null inputs."
  }'

Python (xAI SDK):

import os
from xai_sdk import Client
from xai_sdk.chat import user

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(model="grok-build-0.1")
chat.append(user("Refactor this function to handle null inputs."))
print(chat.sample().content)

JavaScript (AI SDK):

import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const { text } = await generateText({
  model: xai.responses('grok-build-0.1'),
  prompt: 'Refactor this function to handle null inputs.',
});

console.log(text);

---

Skills, Plugins, and Hooks

These three features let you extend Grok with reusable instructions, third-party tools, and automated scripts.

Skills are folders of markdown instructions and scripts that Grok can use. They show up as slash commands in the TUI like /<skill-name>.

Grok looks for skills in:

./.grok/skills/
~/.grok/skills/
~/.grok/plugins/<plugin-name>/skills/

Plugins extend Grok with extra skills, agents, MCP servers, and hooks.

Grok looks for plugins in:

./.grok/plugins/
~/.grok/plugins/
~/.grok/plugins/marketplaces/

Hooks are scripts that run on lifecycle events, such as before or after a tool call. Every hook receives these environment variables automatically: GROK_HOOK_EVENT, GROK_HOOK_NAME, GROK_SESSION_ID, and GROK_WORKSPACE_ROOT.

To manage all of these, open the unified extensions modal in the TUI with any of these commands: /plugins, /hooks, /skills, or /mcps. They all open the same modal with different tabs pre-selected.

Grok also reads Claude Code instruction files (CLAUDE.md, CLAUDE.local.md, .claude/rules/) and AGENTS.md files with no extra setup needed.

---

TUI Modes and Key Commands

The TUI has two main modes you should know:

Plan mode blocks write tools and lets Grok sketch out an approach before making any changes. Useful when you want to review the plan first. Toggle it with /plan.

Always-approve mode skips permission prompts for every tool call. Start Grok with it or toggle in-session:

grok --always-approve

Or set it permanently in ~/.grok/config.toml:

[ui]
permission_mode = "always-approve"

Core TUI commands reference:

Command	What it does
/new	Start a new session
/resume	Resume a previous session
/fork	Fork the current session
/context	View context usage
/model <name>	Switch active model
/compact	Compact conversation history
/rewind	Rewind to an earlier point
/usage	Show token and credit usage
/btw <question>	Ask a side question without interrupting
/share	Share the session via URL
/plan	View the session plan
/always-approve	Toggle always-approve mode

---

ACP: Integrating Grok into Your Own Tools

If you want to embed Grok into an IDE plugin or custom tool instead of using the terminal, use ACP (Agent Client Protocol):

grok agent stdio

This runs Grok as a JSON-RPC agent over stdin/stdout. Your tool sends requests, Grok streams back responses as session/update events.

A minimal Node.js integration looks like this:

import { spawn } from "node:child_process";
import readline from "node:readline";

const proc = spawn("grok", ["agent", "stdio"], {
  stdio: ["pipe", "pipe", "pipe"]
});
const rl = readline.createInterface({ input: proc.stdout });

// Initialize, authenticate, create session, then send prompts
// session/update events carry the streamed response text

The flow is: initialize -> authenticate -> session/new -> session/prompt, then read session/update chunks as the response streams in.

---

Enterprise Deployment

Network Requirements

All connections use HTTPS on port 443 with TLS 1.2 or 1.3.

Required hosts:

Host	Purpose
cli-chat-proxy.grok.com	Inference proxy and settings
auth.x.ai	Authentication

Optional hosts (can be blocked without breaking core features):

Host	Purpose	Impact if blocked
code.grok.com	Session sync and share links	Sessions stay local only
assets.grok.com	Profile images	Avatars won't load
x.ai	CLI installer	Use npm install instead

For TLS-inspecting proxies, install your proxy's CA cert into the OS trust store. Grok honors HTTPS_PROXY, HTTP_PROXY, and NO_PROXY environment variables.

Configuration Layers

Grok merges config from five layers, lowest to highest priority:

Priority	File	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

Values in requirements.toml cannot be overridden. Use it for compliance policies like disabling telemetry, restricting tools, or enforcing sandbox profiles.

Authentication Options

Method	Best for
Browser OIDC (grok login)	Interactive terminals with a browser
Device code (grok login --device-auth)	SSH sessions, containers, headless hosts
External auth provider command	Corporate IdPs and custom token brokers
API key (XAI_API_KEY)	Scripts, CI/CD, headless automation

For enterprise OIDC (Entra ID, Okta, etc.), add this to your config:

[auth.oidc]
issuer = "https://login.yourcompany.com"
client_id = "your-client-id"

For an external token provider:

[auth]
auth_provider_command = "/usr/local/bin/your-auth-provider"

Sandbox Profiles

The sandbox is applied at startup and is irreversible.

Profile	Filesystem write	Child network	Use case
off (default)	Unrestricted	Allowed	No sandbox
workspace	CWD, /tmp, ~/.grok/	Allowed	Normal development
read-only	~/.grok/ and tmp only	Blocked	Code review
strict	CWD, /tmp, ~/.grok/	Blocked	Untrusted repos

Set it with --sandbox workspace or pin it in requirements.toml.

Directories that are always write-protected regardless of profile: ~/.ssh, ~/.gnupg, ~/.aws, ~/.grok/auth, ~/.config/gcloud, ~/.azure.

For untrusted code, combine strict sandbox with locked-down permissions:

grok -p "Review this repo" \
  --permission-mode dontAsk \
  --allow 'Read' \
  --allow 'Bash(git *)' \
  --deny 'Bash(rm -rf *)' \
  --sandbox strict

Zero Data Retention

When ZDR is enabled for a team or enterprise, no prompts, code, or responses are persisted at the inference layer. Local session history is still stored in ~/.grok/ on the user's machine.

---

My SaaS

Acluebox

Build modular and reusable system prompts with my SaaS, Acluebox. Also, free prompt template generators there.

Q&A

1. Do I need an API key to use Grok?

Not for interactive use. On first launch, Grok opens a browser for authentication. You only need an API key for headless environments like servers, containers, or CI pipelines.

2. What is the difference between skills and plugins?

Skills are reusable instruction folders that appear as slash commands in the TUI. Plugins are larger extensions that can bundle skills, hooks, MCP servers, and agents together.

3. How do I prevent Grok from auto-approving dangerous commands?

Even in always-approve mode, you can add explicit deny rules. For example: --deny 'Bash(rm -rf *)'. Commands like rm, chmod, and git push always prompt in ask mode regardless.

4. Can I use Grok with a model other than grok-build-0.1?

You can configure any model in ~/.grok/config.toml under [model.<name>] and set it as the default, or switch to it per-session with grok -m <name> or /model <name> in the TUI.

5. What does grok inspect do?

It shows everything Grok discovered in the current directory: config sources, skills, plugins, hooks, MCP servers, and instruction files. Useful for debugging your setup.

6. How do I use Grok in a CI/CD pipeline?

Set the XAI_API_KEY environment variable and run headless mode with --output-format json and --always-approve. Add --no-auto-update to skip update checks in automated environments.

7. Does Grok work with Claude Code projects?

Yes, fully. Grok automatically reads Claude Code instruction files like CLAUDE.md and CLAUDE.local.md, and supports Claude Code marketplaces, plugins, and MCP configurations without any extra setup.

8. What sandbox profile should I use for reviewing untrusted code?

Use --sandbox strict. It restricts filesystem access to CWD and blocks child processes from making network connections. Combine it with --permission-mode dontAsk and narrow allow rules for maximum safety.

9. What is the ACP protocol used for?

ACP (Agent Client Protocol) lets external tools like IDE plugins embed Grok as a coding agent. It runs over JSON-RPC on stdin/stdout and is the right choice when you want to build your own Grok-powered integration rather than using the terminal UI.

10. How do I enforce a company-wide policy for Grok across developer machines?

Place your policy in /etc/grok/requirements.toml. Settings in this file cannot be overridden by user config or environment variables. You can deploy it via MDM, golden images, or configuration management tools.

References

• Grok Build Overview