# Goose

Goose is an agent for the terminal and desktop. This guide adds the exchange as a custom OpenAI-compatible provider. The provider file holds the URL, the model metadata and the headers.

Each team member can use the same file with a separate buyer key.

## Start with the Liquid CLI

The [Liquid CLI](https://inference.ai.exchange/docs/cli.md) starts Goose with the exchange as its provider. It sets the base URL, the key and the model for that process only. It writes no file of yours. Use it unless you must keep the settings in your own files.

```bash
curl -fsSL https://inference.ai.exchange/cli/install.sh | bash
liquid login
liquid goose
```

Add `--model liquid.auto:cheapest` to rank the offers by price, or `--cap 0.50` to limit what one request can cost. To set up Goose yourself, follow the steps below.

## Before you start

- A workspace with a balance and a `spend` key. See [API keys](https://inference.ai.exchange/docs/keys.md).
- macOS or Linux for the CLI commands below.
- Goose 1.53.0. This setup is tested with that release.

Get the CLI or Desktop from the [Goose 1.53.0 release](https://github.com/aaif-goose/goose/releases/tag/v1.53.0).

## 1. Install Goose CLI

```bash
curl -fsSL https://github.com/aaif-goose/goose/releases/download/v1.53.0/download_cli.sh | GOOSE_VERSION=1.53.0 CONFIGURE=false bash
export PATH="$HOME/.local/bin:$PATH"
```

The installer places the CLI in `~/.local/bin`. The second command adds this directory to the `PATH` of the current shell.

## 2. Create the provider directory

```bash
mkdir -p ~/.config/goose/custom_providers
```

Goose uses `~/.config/goose` on macOS and Linux. These commands assume the default directory.

- If you set `XDG_CONFIG_HOME`, use its `goose/custom_providers` directory.
- If you set `GOOSE_PATH_ROOT`, use its `config/custom_providers` directory. `GOOSE_PATH_ROOT` must be an absolute path.

## 3. Export the buyer key

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

```bash
export LIQUID_API_KEY=sk-liquid-...
```

| Setting          | Purpose                                        |
| ---------------- | ---------------------------------------------- |
| `LIQUID_API_KEY` | The buyer key that Goose reads from the shell. |

Keep this key outside the provider file. Do not share it. Each team member must use their own key.

## 4. Write the provider file

This command replaces only `custom_liquid.json`. Other provider files and the main Goose configuration stay unchanged.

```bash
cat > ~/.config/goose/custom_providers/custom_liquid.json <<'EOF'
{
  "name": "custom_liquid",
  "engine": "openai",
  "display_name": "Liquid Inference",
  "api_key_env": "LIQUID_API_KEY",
  "base_url": "https://router.inference.ai.exchange/v1/chat/completions",
  "models": [
    {
      "name": "liquid.auto",
      "context_limit": 128000
    }
  ],
  "headers": {
    "X-Title": "Goose",
    "x-liquid-cap-usd": "1.00"
  },
  "supports_streaming": true,
  "requires_auth": true,
  "dynamic_models": true
}
EOF
```

| Setting              | Purpose                                                      |
| -------------------- | ------------------------------------------------------------ |
| `name`               | The provider ID for CLI commands.                            |
| `engine`             | Selects the OpenAI-compatible engine.                        |
| `display_name`       | The provider name in the model picker.                       |
| `base_url`           | The full Chat Completions URL, with `/v1/chat/completions`.  |
| `api_key_env`        | Names the variable that holds the buyer key.                 |
| `models`             | Supplies the selected model and its context limit.           |
| `context_limit`      | The number of tokens in the selected model's context window. |
| `headers`            | Sets the request headers below.                              |
| `dynamic_models`     | Enables native model discovery from `GET /v1/models`.        |
| `X-Title`            | Identifies Goose on the receipt.                             |
| `x-liquid-cap-usd`   | Limits the charge for each request.                          |
| `requires_auth`      | Requires a buyer key.                                        |
| `supports_streaming` | Enables response streaming.                                  |

- Keep `api_key_env` as `LIQUID_API_KEY`, without `$`. Goose reads the secret from the environment or its secret storage. Do not put the key in a header.
- The model picker reads the exchange's model list. The file also supplies metadata for the selected model.
- If no live context limit is available, the example uses 128,000 tokens. Change it to match your model.

For the file format, see [Goose custom providers](https://github.com/aaif-goose/goose/blob/v1.53.0/documentation/docs/getting-started/providers.md#configure-custom-provider).

## 5. Check it works

```bash
goose run --provider custom_liquid --model liquid.auto --no-profile --with-builtin developer --max-turns 6 --text "Reply with the word ready"
```

The command selects the provider and model. `--no-profile` omits default extensions. `--with-builtin developer` supplies local file and shell tools.

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

## 6. Start a session

```bash
goose session --provider custom_liquid --model liquid.auto --no-profile --with-builtin developer
```

To use another model, change `--model`. Use an exact model, a router model or a preset. See [Connect an app](https://inference.ai.exchange/docs/connect-overview.md).

To set a default provider and model for future sessions, run this command. Select **Configure Providers**, then **Liquid Inference**, then a model.

```bash
goose configure
```

## Use Goose Desktop

The CLI and Desktop use the same provider directory on macOS and Linux. Install Desktop from the release above. Write the provider file from step 4 before you open Desktop.

Desktop does not inherit the environment of a terminal when you start it from the launcher. Store the buyer key through Desktop instead:

1. Open **Settings → Models → Configure providers**.
2. Select **Liquid Inference**.
3. Enter your buyer key in the **API Key** field.
4. Select **Update Provider**.
5. Open **Settings → Models → Switch models**.
6. Select **Liquid Inference**.
7. Select your model from the list.
8. Select **Select model**.
9. Start a session with a short request.
10. Check its receipt for the Goose client label.

Goose stores the key in its keychain. If the keychain is unavailable or disabled, Goose uses `secrets.yaml`. Keep that file private.

Do not create a second custom provider through Desktop. Use the shared `custom_liquid.json` file, so each team member has the same headers and URL.

See [Goose provider setup](https://github.com/aaif-goose/goose/blob/v1.53.0/documentation/docs/getting-started/providers.md#configure-provider-and-model) for the Desktop controls.

## Control the cost

The `x-liquid-cap-usd` header limits each request. Change its value in the provider file to set a different 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).

## Troubleshooting

| Symptom                            | Cause and fix                                                                                 |
| ---------------------------------- | --------------------------------------------------------------------------------------------- |
| `goose` is absent from `PATH`.     | Add `~/.local/bin` to `PATH` in the shell that starts Goose.                                  |
| The provider is absent.            | Check the provider directory. Check that `custom_liquid.json` is valid JSON. Restart Goose.   |
| Goose cannot get `LIQUID_API_KEY`. | Export the key in the CLI shell. In Desktop, configure the key through the provider controls. |
| `401`                              | Check that the key is valid and has not expired.                                              |
| `403`                              | Check the key's `spend` scope, address restriction and preset rules.                          |
| `402`                              | Add credit to the workspace or check the key's spend limit.                                   |
| `404`                              | Keep the full `/v1/chat/completions` URL in `base_url`.                                       |
| The model is absent.               | Check the live offers and the workspace presets. Use `--model` to select an exact name.       |
| `output_bound_unsupported`         | Select a model with a live offer that accepts the requested output limit.                     |
| `cap_exceeds_buyer_cap`            | Increase the request cap or select a cheaper model.                                           |

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): request caps and presets.