@gonkagate/openhuman-setup

Configure OpenHuman to use GonkaGate as an OpenAI-compatible inference provider in one npx command.

npx @gonkagate/openhuman-setup

Overview

@gonkagate/openhuman-setup is the onboarding CLI for OpenHuman users who want GonkaGate configured as a native OpenAI-compatible custom provider without hand-editing OpenHuman TOML config.

The CLI writes OpenHuman's native cloud_providers shape, routes OpenHuman agent workloads to live GonkaGate model IDs from /v1/models, preserves unrelated config, creates a timestamped backup before replacing an existing config file, and verifies the written result.

Current OpenHuman credential storage is not a safe standalone JSON write target. OpenHuman may store provider secrets in the OS keychain or encrypted JSON depending on runtime policy. This CLI therefore does not mutate auth-profiles.json; it prints the OpenHuman Settings -> AI step for the GonkaGate key and redacts any gp-... value from output.

Quick Start

npx @gonkagate/openhuman-setup

You need:

• Node.js >=22.14.0
• local OpenHuman config on this machine
• a GonkaGate API key from the dashboard
• an active OpenHuman session before custom providers can run inside OpenHuman

What It Does

• Detects the effective OpenHuman config.toml, including OPENHUMAN_WORKSPACE, active user, legacy active workspace, staging root, and pre-login local config.
• Fetches GET https://api.gonkagate.com/v1/models with the user's GonkaGate API key and treats that response as the model source of truth.
• Adds one GonkaGate cloud_providers entry with slug gonkagate.
• Writes workload provider strings for chat, reasoning, agentic, coding, and memory/summarization paths.
• Preserves unrelated TOML values and unrelated cloud providers.
• Creates one timestamped backup before replacing an existing config file.
• Verifies the local config shape after writing.
• Runs a direct GonkaGate /v1/chat/completions smoke with the selected live model.
• Reports OpenHuman sign-in and credential state separately.

Target OpenHuman Contract

• Package: @gonkagate/openhuman-setup
• Provider id: gonkagate
• Base URL: https://api.gonkagate.com/v1
• Transport: /v1/chat/completions
• OpenHuman provider shape: cloud_providers entry plus workload provider strings
• OpenHuman credential key: provider:gonkagate, profile default
• Model catalog: authenticated GET /v1/models with the user's API key

Safe Secret Handling

Allowed secret inputs:

• hidden interactive prompt
• GONKAGATE_API_KEY
• --api-key-stdin

Not allowed:

• plain --api-key
• repository-local secret storage
• shell profile mutation
• direct standalone writes to OpenHuman auth-profiles.json

Non-Interactive Setup

GONKAGATE_API_KEY=gp-... npx @gonkagate/openhuman-setup --yes

Or pass the key through stdin:

printf '%s' "$GONKAGATE_API_KEY" | npx @gonkagate/openhuman-setup --api-key-stdin --yes --json

Model Overrides

By default, the CLI uses the first model returned by GonkaGate /v1/models for all OpenHuman workloads. Override values must be IDs returned by that live response:

npx @gonkagate/openhuman-setup \
  --reasoning-model provider/model-id \
  --agentic-model provider/model-id \
  --coding-model provider/model-id \
  --summarization-model provider/model-id

What This Tool Does Not Do

• It does not install OpenHuman.
• It does not write the old api_url + api_key + model_routes setup shape.
• It does not accept arbitrary custom base URLs.
• It does not use repository-hardcoded GonkaGate model catalogs.
• It does not print or persist gp-... secrets outside approved OpenHuman credential handling.
• It does not directly mutate OpenHuman auth-profiles.json.

Release Proof

Automated release proof is npm run ci plus a temp-workspace CLI smoke. Before publishing, also run one real-workspace smoke with an active OpenHuman session and a real GonkaGate key pasted through OpenHuman Settings -> AI. Current proof notes live in docs/specs/openhuman-setup-prd/release-proof.md.

Local Development

npm install
npm run ci

The CLI can be exercised against a temporary OpenHuman workspace with:

npm run build
GONKAGATE_API_KEY=gp-... OPENHUMAN_WORKSPACE="$(mktemp -d)" node bin/gonkagate-openhuman.js --json --yes

The product requirements for the implementation live in docs/specs/openhuman-setup-prd/spec.md. The current execution plan lives in docs/specs/openhuman-setup-prd/implementation-plan.md.