# Grok Build

Grok Build is xAI's terminal coding agent. It can send its model requests to a custom endpoint. These steps make the exchange that endpoint.

Grok Build reads its settings from `config.toml` in its home folder. The steps use a separate home folder, so your own `~/.grok` and your xAI sign-in stay as they are.

## Start with the Liquid CLI

The [Liquid CLI](https://inference.ai.exchange/docs/cli.md) starts Grok Build with the exchange as its endpoint. It writes the settings below and sets `LIQUID_API_KEY` and `GROK_HOME` for that process only.

```bash
curl -fsSL https://inference.ai.exchange/cli/install.sh | bash
liquid login --browser --keys
liquid keys create laptop --save
liquid grok
```

## Before you start

- A workspace with a balance and a `spend` key. See [API keys](https://inference.ai.exchange/docs/keys.md).
- A model that supports tool calls and streaming.

## 1. Install Grok Build

```bash
npm install -g @xai-official/grok
```

## 2. Create the folder for the settings

```bash
mkdir -p ~/.liquid/grok
```

## 3. Export the buyer key and the folder

Replace the placeholder with your buyer key. Use the same shell for each command below.

```bash
export LIQUID_API_KEY=sk-liquid-...
export GROK_HOME=$HOME/.liquid/grok
```

| Setting          | Purpose                                                                    |
| ---------------- | -------------------------------------------------------------------------- |
| `LIQUID_API_KEY` | Your buyer key. The settings name it in `env_key`.                         |
| `GROK_HOME`      | The folder that holds `config.toml`. It replaces `~/.grok` for this shell. |

## 4. Write the settings

```bash
cat > ~/.liquid/grok/config.toml <<'EOF'
[models]
default = "liquid"
session_summary = "liquid"

[model.liquid]
model = "liquid.auto"
name = "Liquid Inference"
base_url = "https://router.inference.ai.exchange/v1"
env_key = "LIQUID_API_KEY"
api_backend = "chat_completions"
context_window = 128000
max_completion_tokens = 16384
extra_headers = { "x-liquid-cap-usd" = "1.00" }

EOF
```

| Setting                 | Purpose                                                                                   |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| `default`               | The model for new sessions. `liquid` is the `[model.liquid]` entry.                       |
| `session_summary`       | The model for session titles. Without it, Grok Build names an xAI model.                  |
| `model`                 | The model that the exchange receives in each request.                                     |
| `name`                  | The name in the model picker.                                                             |
| `base_url`              | The exchange URL, with `/v1`.                                                             |
| `env_key`               | The variable that holds your buyer key. Grok Build sends it as a bearer token.            |
| `api_backend`           | `chat_completions`, which the exchange accepts.                                           |
| `context_window`        | The input window of the model. Grok Build compacts the conversation before it is full.    |
| `max_completion_tokens` | The output limit of each request.                                                         |
| `extra_headers`         | Headers that Grok Build sends with each request. See [Request headers](#request-headers). |

Grok Build needs no xAI sign-in for these requests. A model that sets its own `env_key` never gets your xAI session token.

## 5. Check it works

```bash
grok -p "Reply with the word ready"
```

The answer must contain `ready`. Open **Credits → Receipts** to check the charge and the Grok Build client label.

## 6. Start a session

```bash
grok
```

## Request headers

`extra_headers` sends these headers with each model request, and only to the
exchange:

| Header             | Value  | Purpose                             |
| ------------------ | ------ | ----------------------------------- |
| `x-liquid-cap-usd` | `1.00` | Limits the charge for each request. |

Grok Build sends the user agent `grok-shell/<release>`. The exchange reads it and labels the receipt as Grok Build, so the settings need no `X-Title`.

## Control the cost

To set a different cap, change the value of `x-liquid-cap-usd`. With `liquid grok`, use `--cap`.

A task can cause several requests, and the request cap does not limit the total charge. Set a spend limit on the key to limit total spend. See [API keys](https://inference.ai.exchange/docs/keys.md).

Use a preset for other purchasing rules. See [Purchasing rules](https://inference.ai.exchange/docs/rules.md).

## Other requests to xAI

Grok Build still contacts xAI for its model catalog, updates and telemetry. These requests do not carry your buyer key. To turn them off, see the `features` and `telemetry` settings in the Grok Build documentation.

## Troubleshooting

| Symptom                              | Cause and fix                                                                                    |
| ------------------------------------ | ------------------------------------------------------------------------------------------------ |
| Grok Build asks you to sign in.      | Check that `GROK_HOME` points at the folder with `config.toml` and that `LIQUID_API_KEY` is set. |
| `401`                                | Check that `LIQUID_API_KEY` holds a valid key that has not expired.                              |
| `402`                                | Add credit to the workspace or raise the key's spend limit.                                      |
| `404`                                | Keep `/v1` at the end of `base_url`.                                                             |
| The error names `no_eligible_offer`. | Read `eligibility.excluded` in the error. It names the rule that each offer did not meet.        |

See [Errors](https://inference.ai.exchange/docs/errors.md) for the exchange's error codes and causes.

## Next steps

- [Market data](https://inference.ai.exchange/docs/market.md): models and live offers.
- [API keys](https://inference.ai.exchange/docs/keys.md): key scope and spend limits.
- [Purchasing rules](https://inference.ai.exchange/docs/rules.md): presets and caps.