# Goose

<img
  src="/brand/banner-a-02.webp"
  alt=""
  loading="lazy"
  width="1280"
  height="549"
  className="brand-band"
/>

[Goose](https://goose-docs.ai) is an open-source AI agent that ships three
ways: a native desktop app for macOS, Linux and Windows, a full CLI for
terminal workflows, and an API you can embed in your own product. It is written
in Rust.

Goose started at Block and moved to the **Agentic AI Foundation** at the Linux
Foundation, a transition Goose announced as complete in April 2026. The repo
now lives at [github.com/aaif-goose/goose](https://github.com/aaif-goose/goose)
and the docs at `goose-docs.ai`. Old `block/goose` and `block.github.io/goose`
links redirect.

It reaches Hyphen through its built-in `openai` provider, pointed somewhere
else.

*Setup guide: this config comes from Goose's official documentation and has
not been run end to end against the gateway. Corrections to [support@hyphen-solution.com](mailto:support@hyphen-solution.com).*

## The easy mistake

Goose does **not** use `OPENAI_BASE_URL`. It splits the URL into two variables:
the host root, and the request path.

```
https://api.hyphen-solution.com/v1/chat/completions
└──────── OPENAI_HOST ────────┘└─ OPENAI_BASE_PATH ─┘
```

Set `OPENAI_HOST` to a URL with no path on it, and put `v1/chat/completions` in
`OPENAI_BASE_PATH` with no leading slash. Get this wrong and every request 404s.

## 1. Get a key

[app.hyphen-solution.com](https://app.hyphen-solution.com) → sign in → pick a
plan or credit pack → **Dashboard → API Keys**. Copy the `sk-...` key.

## 2. Configure

Add to `~/.zshrc` or `~/.bashrc`:

```bash
export GOOSE_PROVIDER="openai"
export GOOSE_MODEL="minimax-m3"
export OPENAI_HOST="https://api.hyphen-solution.com"
export OPENAI_BASE_PATH="v1/chat/completions"
export OPENAI_API_KEY="sk-YOUR_KEY"
```

Then `source ~/.zshrc` or open a new terminal.

### Prefer the config file?

Everything except the key goes in `~/.config/goose/config.yaml`:

```yaml
# ~/.config/goose/config.yaml
GOOSE_PROVIDER: openai
GOOSE_MODEL: minimax-m3
OPENAI_HOST: https://api.hyphen-solution.com
OPENAI_BASE_PATH: v1/chat/completions
```

Leave `OPENAI_API_KEY` in the environment or Goose's keyring. Goose's own docs
advise keeping secrets out of `config.yaml`.

### Or run `goose configure`

The interactive path does the same thing: `goose configure` → **Configure
Providers** → **OpenAI** → paste the key → supply the host URL when prompted.

## 3. Verify

```bash
goose session
```

Then type:

```
Reply with the single word: connected
```

A one-shot version exists too. Check `goose run --help` for the flag your
version uses:

```bash
goose run -t "Reply with the single word: connected"
```

## Named provider instead of hijacking `openai`

If you already use the real OpenAI in Goose and do not want to override its
host, register Hyphen as its own provider. Drop this JSON in
`~/.config/goose/custom_providers/hyphen.json` (Windows:
`%APPDATA%\Block\goose\config\custom_providers\hyphen.json`):

```json
{
  "name": "hyphen",
  "engine": "openai",
  "display_name": "Hyphen",
  "description": "Hyphen gateway, MiniMax M-series",
  "api_key_env": "HYPHEN_API_KEY",
  "base_url": "https://api.hyphen-solution.com/v1/chat/completions",
  "models": [
    { "name": "minimax-m3", "context_limit": 200000 },
    { "name": "minimax-m2.7", "context_limit": 200000 },
    { "name": "minimax-m2.5", "context_limit": 200000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}
```

Note the difference: here `base_url` is the **full** URL including
`/v1/chat/completions`, not the split form. The key comes from whatever
environment variable `api_key_env` names.

```bash
export HYPHEN_API_KEY="sk-YOUR_KEY"
export GOOSE_PROVIDER="hyphen"
export GOOSE_MODEL="minimax-m3"
```

## Troubleshooting

- **404 on every request**. `OPENAI_HOST` has a path on it, or
  `OPENAI_BASE_PATH` has a leading slash. It is `https://api.hyphen-solution.com`
  and `v1/chat/completions`.
- **`401`**. `OPENAI_API_KEY` is unset or wrong. Goose may also have an old key
  in the system keyring from a previous `goose configure` run.
- **Empty or truncated replies**. The M-series reason before answering. Give
  Goose room; see [Choosing a model](/choosing-a-model#the-max_tokens-gotcha).
- **`429`**. Monthly budget spent. See [Rate limits & caps](/rate-limits).
- **Variable names changed?** Confirm the current set at
  [Goose's provider docs](https://goose-docs.ai/docs/getting-started/providers/).
  The docs moved from `block.github.io/goose` to `goose-docs.ai`.

## Related

- [Choosing a model](/choosing-a-model): which model for which job.
- [A small agent loop](/recipes/agent-loop): what Goose is doing under the hood.