Grok Build Integration

Route Grok Build traffic through Headroom for token compression and per-project savings attribution.

Use headroom wrap grok-build to route Grok Build LLM traffic through the local Headroom proxy. The wrapper starts or reuses the proxy, injects a reversible [model.grok-build] override into ~/.grok/config.toml (or $GROK_HOME/config.toml), and prints next steps for launching grok.

Quick Start

headroom wrap grok-build

In another terminal, from the same project directory:

grok

When you are done:

headroom unwrap grok-build

What `wrap grok-build` Does

Step	What happens
Proxy	Starts the Headroom proxy unless `--no-proxy` is set
Model config	Writes or updates `[model.grok-build] base_url` in Grok's `config.toml`, pointing at `http://127.0.0.1:<port>/v1` (with optional `/p/<project>` prefix for savings attribution)
Existing config	If you already have a `[model.grok-build]` table, Headroom rewrites `base_url` in place instead of appending a duplicate table (invalid TOML)
MCP install	`headroom mcp install` can register Headroom MCP via `GrokRegistrar`
Backup	Snapshots `config.toml` to `config.toml.headroom-backup` before the first injection

Options

headroom wrap grok-build \
  --port 8787 \            # Proxy port (default: 8787)
  --no-proxy \             # Use an existing proxy instead of starting one
  --learn \                # Enable live traffic learning
  --memory                 # Enable persistent memory

Environment Variables

Variable	Description
`GROK_HOME`	Override Grok config directory (default: `~/.grok`)
`XAI_API_KEY`	Grok API key (also accepts `GROK_CODE_XAI_API_KEY`)

Persistent Install

grok_build is an install target for headroom install apply --providers manual --target grok_build. The install manifest records proxy env values for Grok Build alongside other wrapped agents.

Unwrap

headroom unwrap grok-build restores the pre-wrap config.toml from backup when available, or strips Headroom marker blocks and in-place base_url rewrites when no backup exists.