> For AI agents: step-by-step setup guide — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), documentation index — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# For AI agents

How to hand off integration to an AI agent: a ready-made prompt for any tool. Below — machine-readable documentation addresses and a skill the agent installs with a single command.

## Prompt for the agent

Send this prompt to your AI agent. It will set up the tool following the instructions below and ask you for the key.

```text
Connect your tool to JoinGonka Gateway — the OpenAI- and Anthropic-compatible API of the Gonka network — following the instructions at https://gate.joingonka.ai/docs/agents.md. I'll provide the key myself: don't save it in repository files and don't modify global environment variables. At the end, verify the connection with a short request and report the result.
```

Below are the instructions themselves. The agent receives them as Markdown at [/docs/agents.md](https://gate.joingonka.ai/docs/agents.md).

## Rules

- The API key is created by a human — in the dashboard at [gate.joingonka.ai](https://gate.joingonka.ai/keys). Don't register an account or create keys yourself: ask the user for a key.
- Keep the key in the `JOINGONKA_API_KEY` environment variable of your terminal session. Don't write it to files tracked by git, don't commit it, and don't print it in the report.
- Don't change the global `OPENAI_*` and `ANTHROPIC_*` variables — neither in the shell profile nor system-wide: other tools of the user read them. The key and URL are written to the tool's own config — that's what the installer does.

## Facts

- Base URL for OpenAI API clients: `https://gate.joingonka.ai/v1`
- Base URL for Anthropic API clients, without `/v1`: `https://gate.joingonka.ai`
- The key is passed in the `Authorization: Bearer jg-…` or `x-api-key: jg-…` header
- The key for model requests starts with `jg-`; the management key `gm-` doesn't grant access to models.
- Recommended model: `MiniMaxAI/MiniMax-M2.7`
- List of available models: `GET https://gate.joingonka.ai/v1/models`
- Per key — up to 120 requests per minute; over the limit you get a 429 response with the `Retry-After` header. Limits and timeouts are in the `GET /v1/capabilities` response, field `limits`.

## Configure

Find the user's tool in the table at the end of the section. If there's a `--tool` value, configure it with the installer; if not, do it manually using the guide.

### Via the installer

One command, no questions: the key comes from an environment variable, the model from a flag. The installer writes the tool's config, saves a copy of the previous one, and verifies the connection with a request to the gateway.

```bash
JOINGONKA_API_KEY=<key> npx -y @joingonka/setup --tool <id> --model MiniMaxAI/MiniMax-M2.7 --non-interactive
```

| Flag | What it does |
| --- | --- |
| `--tool <id>` | Which tool to configure — a value from the tools table. |
| `--model <id>` | Model ID: the recommended one is `MiniMaxAI/MiniMax-M2.7`, all available ones are in `GET /v1/models`. |
| `--non-interactive` | No questions: the key is taken from `JOINGONKA_API_KEY`. |
| `--scope local` | Config in the current project instead of the home directory. Claude Code only; the config file is added to `.gitignore`. |
| `--no-verify` | Don't verify the connection after writing the config. |

| Exit code | What it means |
| --- | --- |
| `0` | Done: the config is written and the test request succeeded. If verification failed due to the network or balance, the installer prints a warning but still exits with code 0 — let the user know. |
| `1` | Setup failed; the reason is in the output: for example, an unknown `--tool` value, `JOINGONKA_API_KEY` not set, or the key doesn't start with `jg-`. |
| `2` | The config is written but the test request failed: check the key and the model ID. |

If the tool was running, restart it: the config is read at startup.

### Manually

For a tool without an installer, open its guide (link in the table below) and set three values:

- base URL — `https://gate.joingonka.ai/v1` for OpenAI API clients or `https://gate.joingonka.ai` for Anthropic API clients;
- key — in the API key field in the tool's settings;
- model — `MiniMaxAI/MiniMax-M2.7` or another one from `GET /v1/models`.

### Tools and guides

| Tool | `--tool` |
| --- | --- |
| [Cursor](https://joingonka.ai/en/knowledge/cursor/) | `cursor` |
| [Claude Code](https://joingonka.ai/en/knowledge/claude-code/) | `claude-code` |
| [OpenClaw](https://joingonka.ai/en/knowledge/openclaw/) | `openclaw` |
| [OpenCode](https://joingonka.ai/en/knowledge/opencode/) | `opencode` |
| [Continue](https://joingonka.ai/en/knowledge/continue-dev/) | `continue` |
| [Cline](https://joingonka.ai/en/knowledge/cline/) | `cline` |
| [Aider](https://joingonka.ai/en/knowledge/aider/) | `aider` |
| [LangChain](https://joingonka.ai/en/knowledge/langchain/) | — |
| [n8n](https://joingonka.ai/en/knowledge/n8n/) | — |
| [Open WebUI](https://joingonka.ai/en/knowledge/open-webui/) | — |
| [LibreChat](https://joingonka.ai/en/knowledge/librechat/) | — |
| [Hermes](https://joingonka.ai/en/knowledge/hermes/) | `hermes` |
| [Kilo Code](https://joingonka.ai/en/knowledge/kilo-code/) | `kilo` |
| [Roo Code](https://joingonka.ai/en/knowledge/roo-code/) | `roo` |
| [LlamaIndex](https://joingonka.ai/en/knowledge/llamaindex/) | — |
| [PydanticAI](https://joingonka.ai/en/knowledge/pydantic-ai/) | — |
| [Vercel AI SDK](https://joingonka.ai/en/knowledge/vercel-ai-sdk/) | — |
| [TanStack AI](https://joingonka.ai/en/knowledge/tanstack-ai/) | — |
| [ZCode](https://joingonka.ai/en/knowledge/zcode/) | `zcode` |
| [JetBrains](https://joingonka.ai/en/knowledge/jetbrains/) | `jetbrains` |
| [Copilot BYOK](https://joingonka.ai/en/knowledge/copilot-byok/) | `copilot-byok` |
| [Zed](https://joingonka.ai/en/knowledge/zed/) | `zed` |
| [Pi](https://joingonka.ai/en/knowledge/pi/) | `pi` |
| [Codex CLI](https://joingonka.ai/en/knowledge/codex/) | `codex` |
| [DeepSeek Harness](https://joingonka.ai/en/knowledge/deepseek-harness/) | — |
| [MiniMax Code](https://joingonka.ai/en/knowledge/minimax-code/) | `minimax-code` |
| [Warp](https://joingonka.ai/en/knowledge/warp/) | — |
| [Trae](https://joingonka.ai/en/knowledge/trae/) | — |
| [Cherry Studio](https://joingonka.ai/en/knowledge/cherry-studio/) | — |
| [omp (Oh My Pi)](https://joingonka.ai/en/knowledge/omp/) | `omp` |
| [OpenHands](https://joingonka.ai/en/knowledge/openhands/) | — |
| [Qwen Code](https://joingonka.ai/en/knowledge/qwen-code/) | `qwen-code` |
| [Goose](https://joingonka.ai/en/knowledge/goose/) | `goose` |
| [Crush](https://joingonka.ai/en/knowledge/crush/) | `crush` |
| [Zoo Code](https://joingonka.ai/en/knowledge/zoo-code/) | `zoo` |
| [Kimi Code](https://joingonka.ai/en/knowledge/kimi-code/) | `kimi-code` |
| [Factory Droid](https://joingonka.ai/en/knowledge/factory-droid/) | `droid` |
| [MiMo Code](https://joingonka.ai/en/knowledge/mimo-code/) | `mimo-code` |

## Verify

Verify the key with a balance request: it doesn't spend tokens, and the key is taken from `JOINGONKA_API_KEY`:

```bash
curl -s https://gate.joingonka.ai/api/balance \
  -H "Authorization: Bearer $JOINGONKA_API_KEY"
```

Verify the URL, key, and model with a short request to the model:

```bash
curl -s https://gate.joingonka.ai/v1/chat/completions \
  -H "Authorization: Bearer $JOINGONKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MiniMaxAI/MiniMax-M2.7", "messages": [{"role": "user", "content": "Say OK"}], "max_tokens": 32}'
```

A `200` response with the model's text means the connection works. The installer runs this check itself: after it, exit code 0 is enough.

## Troubleshoot

The error arrives in the `error` field of the response body — with the type and the reason text.

| Response | What to do |
| --- | --- |
| `401 authentication_error` | Key rejected. Check that it was copied in full and passed in `Authorization: Bearer` or `x-api-key`; a new key is created by the user. |
| `402 insufficient_funds` | No funds in the balance. Tell the user: the balance is topped up in the dashboard. |
| `402 child_key_limit_exceeded` | The child key's limit is exhausted. A different key or a higher limit is needed — the key owner decides that. |
| `403 forbidden` | This is the management key `gm-`: it doesn't grant access to models. You need a `jg-` key. |
| `400 invalid_request_error` | Bad request. If the model isn't found, the error text lists the available IDs — take one from there or from `GET /v1/models`. |
| `404 model_not_found` | That model isn't available right now — pick another one from `GET /v1/models`. |
| `429` | Too many requests or the network is busy. Wait as many seconds as the `Retry-After` header says and retry. |
| `503 model_unavailable` | The network isn't serving the model right now. Switch to the model from the error text or another one from `GET /v1/models`. |
| `504 upstream_timeout` | The network didn't start responding in time. Retry the request; for long responses, enable `stream: true`. |
| `502` | A gateway or network failure — nothing to do with the key. Retry later; network status is on the [Network status](https://gate.joingonka.ai/status) page. |

All response codes and limits are in the [Errors & Rate Limits](https://gate.joingonka.ai/docs/errors) section.

## Report

At the end, tell the user:

- which tool was configured and which config file was written (the installer prints the path, with a copy of the previous one next to it);
- the base URL and model ID;
- the check result: the response code and the model's reply — or why the check couldn't be performed;
- what the user still needs to do themselves: for example, restart the tool or top up their balance.

Do not include the key in the report.

## Machine-readable addresses

| Address | What's there |
| --- | --- |
| [/llms.txt](https://gate.joingonka.ai/llms.txt) | Documentation index for language models. |
| [/llms-full.txt](https://gate.joingonka.ai/llms-full.txt) | The entire documentation in a single file. |
| `/docs/<page>.md` | Markdown version of a documentation page: the same address with `.md` appended ([/docs/models.md](https://gate.joingonka.ai/docs/models.md)) or a page request with the `Accept: text/markdown` header. |
| `GET /v1/capabilities` | Gateway capabilities and limits — the `limits` field. |
| `GET /v1/models` | Models currently available. |
| `GET /api/pricing` | Per-model pricing per 1M tokens and fees. |
| `GET /v1/network-status` | Model status and incidents. |

## Agent skill

The instructions can be installed as a skill for your agent — then it's always at hand, no prompt needed:

```bash
npx skills add https://gate.joingonka.ai
```