Grok Build

TIP

Let the skill configure it

With the ModelFold skills installed, you can simply ask your agent "Configure Grok Build to use ModelFold" and it follows the steps on this page. You can also configure it by hand as described below.

npx skills add https://modelfold.ai --skill modelfold-chat-agents -g -a claude-code -a codex -a grok -y

Key rules

1. Discover models with GET https://modelfold.ai/xai/v1/models, not from memory or training data. This endpoint gives the list Grok Build can run on this prefix.
2. Authenticate with Authorization: Bearer. Every ModelFold endpoint, including the model listing, carries the API key in this one header. A header literally named apikey is rejected with 401.
3. Set api_backend = "responses". Grok Build's default backend is chat_completions, which sends to /v1/chat/completions. ModelFold serves these models on /xai/v1/responses.
4. Fill the model field with an id from the listing. That is the name sent to ModelFold. It is neither the table name [model.<name>] nor Grok Build's own spelling (for example grok-4.6). The listing uses a different set of ids (for example grok-4-6). Copy the id from the list. ModelFold also maps the dotted built-in spelling to the listing id (Grok Build uses it internally, for example to generate session titles), but your config should still use the listing id.
5. Put the table in user-level config. A project-level .grok/config.toml only contributes MCP, plugin and permission keys. A [model.*] table there is not inference configuration.

List available models

curl -s -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  https://modelfold.ai/xai/v1/models |
  jq -r '.data[] | .id'

On Windows (PowerShell), send the same request with curl.exe:

curl.exe -s -H "Authorization: Bearer $env:MODELFOLD_API_KEY" `
  https://modelfold.ai/xai/v1/models | jq -r '.data[].id'

The response has the OpenAI-compatible shape. .data[] is the list: id is the value for model. object, owned_by, created and aliases are boilerplate.

List the ids for the user to choose from. Re-run the listing every time instead of reusing an earlier answer; the model set changes.

Configure

Grok Build configures custom models with [model.<name>] tables. <name> is the key in the model picker, and model is the id sent to ModelFold:

[models]
default = "ModelFold"

[model.ModelFold]
model = "grok-4-6"
base_url = "https://modelfold.ai/xai/v1"
name = "ModelFold"
api_backend = "responses"
env_key = "MODELFOLD_API_KEY"

base_url is the root that requests are sent to. With api_backend = "responses", Grok Build appends /responses itself, so the value is https://modelfold.ai/xai/v1, not the full request URL https://modelfold.ai/xai/v1/responses.

env_key names the environment variable Grok Build reads the credential from and sends as a bearer token. It does not hold the key itself. Prefer it over writing the key into api_key.

You choose the picker key (ModelFold here). [models] default must be that key (or another [model.*] key), not a name from Grok's built-in catalog; otherwise new sessions still go to xAI instead of ModelFold.

Context window

Grok Build uses context_window to decide when to auto-compact. For a custom model without it, Grok Build assumes 200,000 tokens. If the model's detail page on ModelFold states a context length, add it to the table, for example context_window = 256000.

Web search (optional)

Grok Build's web_search tool runs on a separate model. By default that is a built-in Grok model, which has no key in this setup, so web search is disabled (the log shows web_search disabled: resolved config has no API key). Point it at your ModelFold table and enable server-side search:

[models]
default = "ModelFold"
web_search = "ModelFold"

[model.ModelFold]
model = "grok-4-6"
base_url = "https://modelfold.ai/xai/v1"
name = "ModelFold"
api_backend = "responses"
env_key = "MODELFOLD_API_KEY"
supports_backend_search = true

GROK_WEB_SEARCH_MODEL=ModelFold does the same as web_search in [models]. Searches are billed as normal usage of that model.

macOS and Linux

The file is ~/.grok/config.toml. Export the credential in the same shell that starts grok, or add it to your shell profile:

export MODELFOLD_API_KEY=…

Set GROK_HOME to keep the configuration somewhere other than ~/.grok.

Windows (PowerShell)

The file is %USERPROFILE%\.grok\config.toml, with identical content.

$env:MODELFOLD_API_KEY = "…"
setx MODELFOLD_API_KEY "…"

Verify the setup

grok models should list the custom key. grok inspect reports which config file is in effect. Start grok in a shell where MODELFOLD_API_KEY is set and send a message, or run grok -p "…" -m ModelFold.

RUST_LOG=debug GROK_LOG_FILE=/tmp/grok.log grok writes a request trace. Check the base_url and the model id.

Common pitfalls

1. A header named apikey. ModelFold returns 401. Put the key in Authorization: Bearer.
2. The full request URL in base_url. With api_backend = "responses", Grok Build appends /responses itself, so a base_url ending in /responses becomes /responses/responses.
3. No api_backend. The default is chat_completions, which sends to /v1/chat/completions, not /xai/v1/responses.
4. Grok's own model name in model. ModelFold reads the model field of [model.<name>], which should be an id from the listing. A built-in spelling such as grok-4.6 is not that id; ModelFold maps it as a fallback, but do not rely on that in config.
5. [model.*] in the project-level .grok/config.toml. That file does not carry inference configuration. Use ~/.grok/config.toml.
6. The key itself in env_key. It takes the name of an environment variable. The key lives in that variable, not in the config file.
7. setx does not affect the current window. It applies to windows opened afterwards. Set $env: as well to use it right away.
8. PowerShell curl. It is an alias for Invoke-WebRequest and does not accept these arguments. Use curl.exe.
9. Web search does nothing. Without web_search = "ModelFold" and supports_backend_search = true, the search tool is disabled and the agent falls back to fetching pages itself. See "Web search" above.

To use a model from a listing that isn't on this protocol, see When protocols don't match on the Install modelfold-chat-agents page.