https://github.com/gonkagate/kilo-setup
Install GonkaGate for Kilo Code with one npx command. Secure setup CLI for Kilo/KiloCode custom provider config, OpenAI-compatible AI models, and safe API key storage.
https://github.com/gonkagate/kilo-setup
ai-cli ai-coding ai-models api-key cli coding-agent custom-provider developer-tools gonkagate kilo kilo-code kilocode llm model-discovery npx openai-api openai-compatible secure-setup typescript
Last synced: 1 day ago
JSON representation
Install GonkaGate for Kilo Code with one npx command. Secure setup CLI for Kilo/KiloCode custom provider config, OpenAI-compatible AI models, and safe API key storage.
- Host: GitHub
- URL: https://github.com/gonkagate/kilo-setup
- Owner: GonkaGate
- License: apache-2.0
- Created: 2026-04-14T10:18:44.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-07-06T15:23:39.000Z (8 days ago)
- Last Synced: 2026-07-06T17:11:36.159Z (7 days ago)
- Topics: ai-cli, ai-coding, ai-models, api-key, cli, coding-agent, custom-provider, developer-tools, gonkagate, kilo, kilo-code, kilocode, llm, model-discovery, npx, openai-api, openai-compatible, secure-setup, typescript
- Language: TypeScript
- Homepage: https://gonkagate.com
- Size: 44.2 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: docs/security.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# kilo-setup
Set up local `kilo` to use GonkaGate in one `npx` command.
```bash
npx @gonkagate/kilo-setup
```
[](https://gonkagate.com/en?utm_source=github&utm_medium=referral&utm_campaign=kilo_setup&utm_content=readme_badge_website)
[](https://gonkagate.com/en/docs?utm_source=github&utm_medium=referral&utm_campaign=kilo_setup&utm_content=readme_badge_docs)
[](https://gonkagate.com/en/register?utm_source=github&utm_medium=referral&utm_campaign=kilo_setup&utm_content=readme_badge_api_key)
[](https://t.me/gonkagate)
[](https://x.com/gonkagate)
[](https://www.linkedin.com/company/gonkagate)
## See It In Action
From API key to a working `kilo` setup in one short walkthrough:
[](https://raw.githubusercontent.com/GonkaGate/kilo-setup/main/.github/assets/gonkagate-kilo-setup-demo.mp4)
Need an API key first? [Get one on GonkaGate](https://gonkagate.com/en/register?utm_source=github&utm_medium=referral&utm_campaign=kilo_setup&utm_content=readme_api_key_cta).
## Overview
`@gonkagate/kilo-setup` is for people who already have Kilo installed and want
the shortest safe path to GonkaGate without hand-editing Kilo config, putting
secrets into a repository, or learning Kilo provider internals first.
Prefer product links first? The resource buttons above jump to the website,
docs, API-key dashboard, Telegram updates, X, and LinkedIn.
## Why This Exists
This installer configures an existing local `kilo` or `kilocode` install to
use GonkaGate, writes the minimum safe config, verifies the effective result,
and then sends you back to plain `kilo`.
What it does for you:
- keeps the secret out of repo-local config by default
- preserves unrelated Kilo settings instead of replacing whole files
- supports interactive and non-interactive setup
- verifies the intended Kilo result instead of assuming file writes worked
- keeps the public contract narrow and honest
What it does not do:
- it does not install Kilo itself
- it does not install or pin Kilo versions for you
- it does not claim GonkaGate `responses` support today
- it does not claim native Windows production support yet
## Before You Start
You need:
- Node `>=22.14.0`
- local `kilo` installed and available on `PATH`, or the fallback `kilocode`
command
- local Kilo matching the minimum accepted floor: `@kilocode/cli >=7.2.0`
- a GonkaGate API key in the usual `gp-...` format from the
[dashboard](https://gonkagate.com/en/register?utm_source=github&utm_medium=referral&utm_campaign=kilo_setup&utm_content=readme_api_key_cta)
Current public baseline:
- package: `@gonkagate/kilo-setup`
- primary command after setup: `kilo`
- current transport target: `chat/completions`
- model source of truth: `GET https://api.gonkagate.com/v1/models` after safe
API-key intake
- Kilo's OpenCode-style `/models` picker receives every fetched GonkaGate model
- installer-managed `limit.output = 8192` for each fetched model entry
- no native Windows production claim yet
## Shortest Start Path
### Interactive setup
Use this when you are setting up your own machine:
```bash
npx @gonkagate/kilo-setup
```
The installer will:
1. detect `kilo`, or fall back to `kilocode`
2. verify local Kilo is at least `@kilocode/cli >=7.2.0`
3. collect your API key through a hidden prompt
4. fetch the live GonkaGate model catalog from `/v1/models`
5. show the live model choices
6. write the fetched GonkaGate provider model catalog for Kilo's `/models`
picker
7. choose the recommended scope automatically:
- inside a git repository: `project`
- outside a repository: `user`
8. write the managed config and verify the result
9. return you to normal `kilo` usage
On interactive reruns, the installer asks about scope only if the last
installer-managed scope differs from the new recommendation.
If you launch the installer from inside an active `kilo` terminal session, the
durable install can still succeed while that specific shell remains overridden
by Kilo runtime config until you exit the session and return to plain `kilo`.
### Non-interactive setup
Use this for scripts, automation, or repeatable local setup:
```bash
npx @gonkagate/kilo-setup --scope project --yes
```
Optional Kilo UI-model cache cleanup:
```bash
npx @gonkagate/kilo-setup --scope project --clear-kilo-model-cache --yes
```
With a key from the environment:
```bash
GONKAGATE_API_KEY="$GONKAGATE_API_KEY" npx @gonkagate/kilo-setup --scope user --yes
```
With a key through stdin:
```bash
printf '%s' "$GONKAGATE_API_KEY" | npx @gonkagate/kilo-setup --api-key-stdin --scope project --yes --json
```
If you run non-interactively, pass `--scope` or `--yes`. Inside a git
repository, the recommended default is usually `project`; outside a repo, it
is usually `user`.
## `user` vs `project` Scope
Use `user` when you want GonkaGate available on this machine in general.
- writes the provider definition and activation into user-level Kilo config
- good default outside a repository
Use `project` when you want this repository to activate GonkaGate by default.
- keeps the provider definition and secret binding in user config
- writes only activation settings into `.kilo/kilo.jsonc`
- good default inside a git repository
- the installer also warns when Kilo's global UI model cache could make another
repository reopen on the last selected GonkaGate model
Important limit:
`project` scope is commit-safe by default, but it is not self-sufficient on a
brand-new machine. Each participating machine still needs a compatible
user-level `provider.gonkagate` definition, usually by running the installer on
that machine too.
## Safe Ways To Pass The API Key
Supported inputs:
- hidden interactive prompt
- `GONKAGATE_API_KEY`
- `--api-key-stdin`
Intentionally not supported:
- plain `--api-key`
- `.env` generation
- shell profile mutation
- repository-local secret storage
- direct writes to Kilo `auth.json`
The installer will never accept plain `--api-key`.
The installer never prints the GonkaGate key.
## Where Files Go
Current managed locations:
- user-level secret: `~/.gonkagate/kilo/api-key`
- durable global config target: `~/.config/kilo/kilo.jsonc`
- durable project config target: `.kilo/kilo.jsonc`
Scope rules:
- `user` scope writes provider and activation into user config
- `project` scope keeps the provider definition in user config and writes only
activation into project config
- project config stays secret-free by default
## Current Honest Limits
This repository intentionally stays narrow today:
- minimum accepted Kilo floor: `@kilocode/cli >=7.2.0`
- current transport target: `chat/completions`
- model availability comes from authenticated `GET /v1/models`
- if no explicit model is selected, setup uses the API-provided default when
present, otherwise the first returned model
- real-path Kilo verification is not the production default
- native Windows production support is not claimed yet
- future Kilo releases are not pre-blocked by version, but observed
compatibility breaks still need fixes
- new transport flows are not implied just because this package exists
The shipped runtime treats effective Kilo config as the real success gate. It
uses the local resolver as the durable verifier and keeps the XDG-isolated
`kilo debug config` oracle as a compatibility check with fake secrets. Inside
that sandbox, mirrored global Kilo config is written into the sandbox XDG
config tree so Kilo loads the same user-level provider layer the local
resolver inspected. The oracle sandbox is created in temporary storage outside
the repository and is cleaned up after verification, so setup should not leave
`home/`, `xdg/`, `npm-cache`, or mirrored `workspace/` trees in git.
## Need More Detail?
- [User guide](https://github.com/GonkaGate/kilo-setup/blob/main/docs/user-guide.md)
- [How it works](https://github.com/GonkaGate/kilo-setup/blob/main/docs/how-it-works.md)
- [Security notes](https://github.com/GonkaGate/kilo-setup/blob/main/docs/security.md)
- [Troubleshooting](https://github.com/GonkaGate/kilo-setup/blob/main/docs/troubleshooting.md)
- [Release and publishing runbook](https://github.com/GonkaGate/kilo-setup/blob/main/docs/publishing.md)
## Development
```bash
npm install
npm run ci
```
Useful commands:
```bash
npm run build
npm run typecheck
npm test
npm run format:check
npm run package:check
node bin/gonkagate-kilo.js --help
node bin/gonkagate-kilo.js --json
```