https://github.com/gonkagate/zeroclaw-setup
Install GonkaGate for ZeroClaw with one npx command. Setup and verify CLI for custom OpenAI-compatible provider config, live model checks, and hidden API key setup.
https://github.com/gonkagate/zeroclaw-setup
ai-cli ai-coding ai-models api-key cli coding-agent custom-provider developer-tools gonkagate llm model-checks npx openai-api openai-compatible secure-setup typescript verification zeroclaw zeroclaw-setup
Last synced: 1 day ago
JSON representation
Install GonkaGate for ZeroClaw with one npx command. Setup and verify CLI for custom OpenAI-compatible provider config, live model checks, and hidden API key setup.
- Host: GitHub
- URL: https://github.com/gonkagate/zeroclaw-setup
- Owner: GonkaGate
- License: apache-2.0
- Created: 2026-04-17T12:22:27.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-07-06T23:31:40.000Z (7 days ago)
- Last Synced: 2026-07-07T01:10:59.599Z (7 days ago)
- Topics: ai-cli, ai-coding, ai-models, api-key, cli, coding-agent, custom-provider, developer-tools, gonkagate, llm, model-checks, npx, openai-api, openai-compatible, secure-setup, typescript, verification, zeroclaw, zeroclaw-setup
- Language: TypeScript
- Homepage: https://gonkagate.com
- Size: 417 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: docs/security.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# zeroclaw-setup
Set up local ZeroClaw to use GonkaGate in one `npx` command.
```bash
npx zeroclaw-setup
```
[](https://gonkagate.com/en?utm_source=github&utm_medium=referral&utm_campaign=zeroclaw_setup&utm_content=readme_badge_website)
[](https://gonkagate.com/en/docs?utm_source=github&utm_medium=referral&utm_campaign=zeroclaw_setup&utm_content=readme_badge_docs)
[](https://gonkagate.com/en/register?utm_source=github&utm_medium=referral&utm_campaign=zeroclaw_setup&utm_content=readme_badge_api_key)
[](https://t.me/gonkagate)
[](https://x.com/gonkagate)
[](https://www.linkedin.com/company/gonkagate)
## Overview
Onboarding-first ZeroClaw utility for configuring GonkaGate as the primary
custom provider.
The repository is still intentionally narrow: it owns only the GonkaGate
provider contract, delegates persistence to ZeroClaw-native seams, and stays
on the audited stable ZeroClaw `v0.6.9` config contract.
Follow-up verification command:
```bash
npx zeroclaw-setup verify
```
Current status:
- repository infrastructure is ready for active development and publishing
- install now performs real Phase 2 mutation work on audited ZeroClaw
`v0.6.9`
- first-run setup uses a proven two-step native path:
`zeroclaw onboard --quick --provider custom:https://api.gonkagate.com/v1 --model `
followed by the hidden native `zeroclaw props set api-key` prompt
- first-run mutation stays intentionally limited to that hidden native prompt
path; stdin-fed secret transport remains blocked because it is not part of
the shipped proof on audited `v0.6.9`
- existing-config updates use a split native write seam:
`default-provider` and `default-model` go through
`zeroclaw props set --no-interactive`, while `api-key` stays on the hidden
native `zeroclaw props set api-key` path
- after hidden GonkaGate key entry, install calls
`GET https://api.gonkagate.com/v1/models`, validates the response shape, and
uses the returned live model IDs for model prompts, `--model` validation, and
ZeroClaw config mutation
- empty or malformed live model catalogs block setup before any ZeroClaw config
mutation
- install refuses mutation when the runtime is active or ambiguous, when the
config contains unknown top-level keys, or when the installed ZeroClaw
runtime is missing, unparseable, or older than `v0.6.9`
- `verify` now performs the shipped Phase 3 read-only verdict flow: minimum
version gating, active config resolution, saved-config
contract checks, runtime summary through `zeroclaw status`, and advisory
`zeroclaw doctor` output
- `verify` returns explicit `pass`, `warn-shadowed`, and `fail` results, with
the exact warning `saved config is correct but inactive` when env overrides
shadow an otherwise-correct saved GonkaGate contract
## Quick Start
```bash
npm install
npm run ci
npm run dev -- --help
```
Development entrypoints:
- `npm run dev`
- `npm run dev -- verify`
- `npm run build`
- `npm run lint`
- `npm test`
- `npm run ci`
## What Is Already Set Up
- TypeScript ESM project structure with separate typecheck and build configs
- ESLint + Prettier wired into local scripts and CI
- packaged CLI binary at `zeroclaw-setup`
- GitHub Actions for CI, release-please, and npm publish
- release metadata files aligned with sibling `*-setup` repositories
- mirrored `.agents` and `.claude` skill packs copied from `opencode-setup`
- starter docs under `docs/`
- node:test coverage for version gating, config resolution, first-run proof,
native write sequencing, restore boundaries, live model catalog, docs, and
package metadata
## Repository Layout
```text
bin/ packaged CLI entrypoint
docs/ docs, security notes, implementation plan, specs mirror
scripts/ repository utility scripts
src/constants/ fixed provider data
src/install/ install and verify runtime seams
test/ fast node:test coverage for install, verify, and repo contracts
.agents/skills/ mirrored local skill pack for agent workflows
.claude/skills/ mirrored local skill pack for Claude-compatible workflows
```
## Product Contract Seeded In Code
The code hard-codes the GonkaGate contract from the PRD:
- provider base URL: `https://api.gonkagate.com/v1`
- provider key: `custom:https://api.gonkagate.com/v1`
- managed config fields:
- `default_provider`
- `api_key`
- `default_model`
- shipped first-run path:
- `zeroclaw onboard --quick --provider custom:https://api.gonkagate.com/v1 --model `
- hidden native `zeroclaw props set api-key`
- first-run mutation stays blocked when the API key would need stdin or
another unproven transport
- shipped existing-config path:
- `zeroclaw props set --no-interactive default-provider custom:https://api.gonkagate.com/v1`
- `zeroclaw props set --no-interactive default-model `
- hidden native `zeroclaw props set api-key`
- runtime-quiesced sequencing with non-secret restore after pre-secret and
post-secret failures
- explicit secret remediation because stable native read-back does not expose
the prior `api-key`
- saved-config confirmation uses `api_key` set/unset evidence only; literal
secret read-back is not part of the wrapper contract
- chosen v1 verify shadowing behavior:
- explicit `saved config is correct but inactive` warning when env overrides
mask the saved GonkaGate contract
- shipped verify evidence split:
- `zeroclaw status` informs the effective runtime verdict
- `zeroclaw doctor` remains advisory troubleshooting context
- live model catalog gate:
- endpoint: `GET https://api.gonkagate.com/v1/models`
- auth: `Authorization: Bearer `
- response trust boundary: root object with a `data` array of objects whose
`id` fields are non-empty strings and optional string `name` fields
- duplicate live model IDs are deduped
- install fails cleanly on empty or malformed live catalogs before model
selection or native writes
- the selected live model ID is written directly to `default_model`
- public install flag surface:
- optional `--model ` validated against the fetched live catalog
- env override checks:
- `ZEROCLAW_PROVIDER`
- `ZEROCLAW_MODEL_PROVIDER`
- `MODEL_PROVIDER`
- `PROVIDER`
- `ZEROCLAW_MODEL`
- `MODEL`
- `ZEROCLAW_API_KEY`
- `API_KEY`
- ZeroClaw runtime gate:
- minimum supported version: audited stable ZeroClaw `v0.6.9`
- newer versions are not blocked solely because they are newer
## CLI Status
The package exposes these public commands:
```bash
npx zeroclaw-setup
npx zeroclaw-setup verify
```
Current shipped behavior:
- `npx zeroclaw-setup` performs real Phase 2 install mutation when the
installed ZeroClaw runtime is at least audited `v0.6.9` and read-only gating
passes
- install asks for a hidden GonkaGate API key after the chosen mutation path is
known and the runtime quiesce gate has passed, checks the live
`GET /v1/models` catalog, then prompts for a live model when `--model` is
omitted in an interactive terminal
- non-interactive/default installs without `--model` use the first valid live
model returned by `/v1/models`
- the wrapper-collected key is used for the live catalog check; public native
storage paths still let ZeroClaw collect the persisted `api-key` through
`zeroclaw props set api-key`, so first-run stdin secret persistence remains
blocked
- first-run install is shipped only when ZeroClaw can collect the secret
through its hidden native `zeroclaw props set api-key` prompt
- install does not place the GonkaGate API key on argv in the shipped happy
path
- `npx zeroclaw-setup verify` now performs shipped read-only verification,
including final `pass` / `warn-shadowed` / `fail` verdicts
- verify and saved-config confirmation use `api_key` set/unset evidence only;
they do not claim literal saved secret read-back
## Docs
- [docs/README.md](docs/README.md) current-truth documentation index
- [docs/how-it-works.md](docs/how-it-works.md)
- [docs/implementation-plan.md](docs/implementation-plan.md) historical
execution record
- [docs/prd-task-breakdown.md](docs/prd-task-breakdown.md) historical planning
checklist
- [docs/security.md](docs/security.md)
- [docs/troubleshooting.md](docs/troubleshooting.md)
- [docs/specs/zeroclaw-setup-prd/spec.md](docs/specs/zeroclaw-setup-prd/spec.md)
## Release Flow
The repository follows the same release automation pattern as neighboring
GonkaGate CLI utilities:
1. `CI` runs on push and pull request
2. `Release Please` opens and updates release PRs from conventional commits
3. tags dispatch `Publish (npm)` with OIDC-based provenance publishing
## License
Apache-2.0