Skip to content
NoviaHub Docs

Command-line agents

Grok Build

Add NoviaHub models to Grok Build as custom models in config.toml, then verify the setup and switch models.

Grok Build is xAI’s coding agent (“a powerful and extensible coding agent”). You can use it in a full-screen terminal interface or run it headless from scripts. Its config file accepts custom models, each with its own address and protocol, which is how you connect it to NoviaHub.

Prerequisites

Section titled “Prerequisites”

Install

Section titled “Install”
终端窗口
curl -fsSL https://x.ai/cli/install.sh | bash

Configure NoviaHub

Section titled “Configure NoviaHub”

  1. Store your API key in the environment variable NOVIAHUB_API_KEY. The config file only names the variable; Grok Build reads the key from it at start-up.

    终端窗口
    # macOS uses zsh by default; with bash on Linux, use ~/.bashrc instead of ~/.zshrc
    echo 'export NOVIAHUB_API_KEY="sk-..."' >> ~/.zshrc
    source ~/.zshrc

  2. Edit the config file, creating it if it doesn’t exist:

    • macOS / Linux: ~/.grok/config.toml
    • Windows: %USERPROFILE%\.grok\config.toml

    Add the following. It defines two models: deepseek-v4-flash over OpenAI Chat Completions and claude-sonnet-5 over Anthropic Messages.

    ~/.grok/config.toml
    [model.deepseek-v4-flash]
    model = "deepseek-v4-flash"
    name = "deepseek-v4-flash (NoviaHub)"
    base_url = "https://noviahub.com/v1"
    env_key = "NOVIAHUB_API_KEY"
    api_backend = "chat_completions"
    context_window = 1000000
    

    [model.claude-sonnet-5]
    model = "claude-sonnet-5"
    name = "claude-sonnet-5 (NoviaHub)"
    base_url = "https://noviahub.com/v1"
    env_key = "NOVIAHUB_API_KEY"
    api_backend = "messages"
    context_window = 1000000
    

    [models]
    default = "deepseek-v4-flash"

    What each field means:

    Field Meaning
    [model.<name>] The model’s name inside Grok Build; you use it to switch models. Quote names that contain a . (for example gpt-5.6-sol): [model."gpt-5.6-sol"].
    model The model ID sent to NoviaHub. It must match Models & Pricing exactly.
    name The label shown in the model picker; any text works.
    base_url https://noviahub.com/v1. Keep /v1 for all three protocols: Grok Build appends /chat/completions, /responses or /messages.
    env_key The environment variable that holds the key.
    api_backend The protocol; see the next section. Defaults to chat_completions.
    context_window The model’s context length, which Grok Build uses to decide when to compact the conversation. According to the docs, a new model without this field is treated as 200,000 tokens. The values above come from Models & Pricing on 2026-09-28; use the Context figure shown there.
    default under [models] The model used at start-up: one of the [model.<name>] names above.

  3. Open a new terminal, go to your project folder and run grok. As long as NOVIAHUB_API_KEY has a value in that terminal, Grok Build doesn’t ask you to sign in to an xAI account; see Troubleshooting below.

Choosing api_backend

Section titled “Choosing api_backend”

api_backend must match a protocol the model supports. Open the model under Models & Pricing and look at its endpoint labels:

api_backend Endpoint called Endpoint label the model needs
chat_completions (default) /v1/chat/completions Chat
responses /v1/responses Response
messages /v1/messages Anthropic

On 2026-09-28 every text model on NoviaHub had the Chat label, so chat_completions is the safe choice. For Claude models, messages is recommended; see Protocol conversion for why.

Verify

Section titled “Verify”
终端窗口
# List all available models; the two added above should appear
grok models


# Ask one question with a given model, without opening the interface
grok -p "Introduce yourself in one sentence." -m deepseek-v4-flash

If you get an answer and the call shows up in NoviaHub’s Usage Logs, the setup works. After changing the config you can also run grok inspect to see which configuration Grok Build picked up.

Switch models

Section titled “Switch models”
  • Type /model claude-sonnet-5 in the interface (or the short form /m claude-sonnet-5).
  • Press Ctrl+M while the scrollback pane has focus to open the model picker.
  • Choose at start-up: grok -m claude-sonnet-5.
  • Change default under [models] in the config file.

To use another model, add a [model.<name>] section for it first.

Troubleshooting

Section titled “Troubleshooting”

Do I need to sign in to an xAI account on first launch? No. The docs say Grok Build opens a browser to sign in on first launch, but its source adds a rule: if any model has its own key at start-up (the variable named by env_key has a value, or api_key is set), Grok Build goes straight to the interface without the sign-in screen. The docs also say a model’s own env_key / api_key takes precedence over a signed-in session.

So if a browser still opens, NOVIAHUB_API_KEY usually has no value in that terminal. Quit Grok Build, run echo $NOVIAHUB_API_KEY (echo $env:NOVIAHUB_API_KEY in PowerShell) and check that it prints the key, then start it again.

Your model is missing from grok models Check the spelling of the [model.<name>] section in config.toml, and quote names that contain a ..

Errors about reasoning.summary with the responses backend According to the docs, Grok Build asks for a concise reasoning summary (reasoning.summary) on the Responses API by default. Add reasoning_summary = "none" to that model’s section to stop sending the field.

401 Invalid token The key is wrong, the environment variable isn’t set, or the key is disabled, expired or out of quota. First run echo $NOVIAHUB_API_KEY in the same terminal (echo $env:NOVIAHUB_API_KEY in PowerShell) and check that it prints the key; then check the key’s status on the API Keys page, see The four statuses.

403 insufficient_user_quota Your account balance has run out. Top up first.

References

Section titled “References”

Checked on 2026-09-28 and 2026-09-29: