Connect Pi to NekoCloud

Pi supports OpenAI-compatible gateways through its custom model file. This guide follows the current earendil-works/pi documentation rather than assuming the old repository's key-resolution behavior. NekoCloud has not individually acceptance-tested this toolchain.1

1. Prepare and install

Current official installation command; skip it if already installed:2

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Create a NekoCloud key and check balance, group permissions, and the exact ID in the model plaza. Back up ~/.pi/agent/models.json. If providers exists, add only nekocloud and preserve the other providers. Configuration belongs to the user running Pi; for remote projects, check the remote configuration.

2. Minimal configuration

Set the variable in your terminal and edit the file above. The example is complete valid JSON:

export NEKOCLOUD_API_KEY="REPLACE_WITH_API_KEY"

{
  "providers": {
    "nekocloud": {
      "baseUrl": "https://api.nekocloud.vip/v1",
      "api": "openai-completions",
      "apiKey": "${NEKOCLOUD_API_KEY}",
      "models": [
        {
          "id": "REPLACE_WITH_MODEL_ID"
        }
      ]
    }
  }
}

Field	Meaning
providers.nekocloud	Custom provider name
baseUrl	NekoCloud OpenAI base URL
api	openai-completions means Chat Completions
apiKey	${NEKOCLOUD_API_KEY} resolves an environment variable
models[].id	Exact model ID sent to the API

The current version supports $VAR and ${VAR}. A bare NEKOCLOUD_API_KEY is a literal key, not an environment-variable reference.1 This example omits prices and context/output limits: client default metadata is not a NekoCloud capability promise. Verify before long tasks, and never interpret a default zero estimate as free service.

3. Select and reload

Start in a test project with only read-only built-in tools:2

pi --provider nekocloud --model REPLACE_WITH_MODEL_ID --tools read,grep,find,ls

Opening /model reloads models.json each time, so file edits need no restart. Environment changes require restarting Pi from the same terminal.1 Verify the provider and ID in the picker; /reload is not an environment refresh. Do not enable images, reasoning, or Responses without confirming support.

4. Read-only verification and security

Tests can incur charges; confirm consent first. Send a greeting, then request a read call to read README and summarize it with a quote. Inspect the actual tool result and final answer, and confirm files are unchanged. The read-only tool list does not constrain third-party extensions; do not load untrusted project extensions for the first test.2 Compare /session or footer token statistics with NekoCloud records by time, model, and tokens. Local cost is a metadata-based estimate, not the bill.2

Do not upload keys, backups, or sessions to repositories or sharing services. Prefer hidden input followed by an export. For 401, check variable availability; for 404, check model and path; for 400, check protocol. Adjust compat only after identifying a specific unsupported field, rather than blindly disabling capability checks.

Official sources

• 1 — Current custom model configuration
• 2 — Installation, tools, and session commands