Skip to content
Docs

Grok Build with AI Gateway

Grok Build is SpaceXAI's terminal-based coding agent. Point it at AI Gateway to:

  • Use models from other providers, not only SpaceXAI ones
  • Monitor traffic and spend in your AI Gateway Overview
  • View detailed traces in Vercel Observability under AI
  • Switch models from the in-CLI picker without re-authenticating

Set two environment variables and every request routes through AI Gateway, with the model picker populated from the gateway's catalog.

Run the Vercel CLI setup command for Grok Build:

terminal
npx vercel@latest ai-gateway setup --agent grok

The command provisions or reuses a key, configures the gateway endpoint and default model in ~/.grok/config.toml, and adds the key to your shell profile.

If you can't use the Vercel CLI, configure Grok Build manually:

  1. Follow the installation instructions in the SpaceXAI documentation. Verify the install:

    grok --version
  2. Set both variables in your shell configuration file, for example ~/.zshrc or ~/.bashrc:

    export GROK_MODELS_BASE_URL="https://ai-gateway.vercel.sh/coding-agent/v1"
    export GROK_CODE_XAI_API_KEY="your-ai-gateway-api-key"

    Replace your-ai-gateway-api-key with a key from the AI Gateway API Keys page. See API key authentication for details.

    https://ai-gateway.vercel.sh/coding-agent/v1 is the coding agent surface, the default base URL for agents that have no dedicated endpoint. Except for model discovery, it passes through to the gateway's standard /v1 handlers, so routing, billing, and errors are unchanged.

    Reload your shell:

    source ~/.zshrc  # or source ~/.bashrc

    When GROK_MODELS_BASE_URL is set, Grok Build sends the API key as Authorization: Bearer instead of session-based auth. If you've previously signed in with grok login, run grok logout first. An existing session takes precedence over the API key.

  3. Start a session:

    grok

    Press Ctrl+M to open the model picker. It lists the models AI Gateway exposes at /coding-agent/v1/models, which omits models that a coding agent can't use for text responses, such as embedding, image, and video models. To set a default model, add it to ~/.grok/config.toml:

    ~/.grok/config.toml
    [models]
    default = "spacexai/grok-4.5"
    # Or try other models:
    # default = "anthropic/claude-sonnet-5"
    # default = "openai/gpt-6-astra"
    # default = "google/gemini-3.1-pro-preview"

    To confirm requests are flowing through the gateway, check your AI Gateway Overview in the Vercel dashboard.

Grok Build's web search tool requires a separate model configured to use the OpenAI Responses API.

  1. Add the entry below to ~/.grok/config.toml:

    ~/.grok/config.toml
    [model.vercel-search]
    model = "spacexai/grok-4.5"
    base_url = "https://ai-gateway.vercel.sh/coding-agent/v1"
    api_backend = "responses"
  2. Set the env var in your shell configuration file:

    export GROK_WEB_SEARCH_MODEL="vercel-search"

    Reload your shell and restart Grok Build for the change to take effect.

Last updated September 13, 2026

Was this helpful?

supported.