cnb2api

Turn CNB Cloud Workspace In-Network AI into a Production-Ready API Gateway

Get Up to 200M Free DeepSeek Tokens Monthly · Zero External Dependencies · 7×24h Self-Healing HA

OpenAI + Anthropic Dual Protocols · Zero-Config Claude Code Direct Connect · v5.2 Architecture · Terminal Quota Dashboard

English · 简体中文

TL;DR: CNB grants verified orgs 500 ~ 1,166 AI Credits and 1,600 compute core-hours monthly for free. Combined with CNB's 30x prompt caching discount, you can enjoy up to ~200 Million DeepSeek Tokens per month for free! However, the AI completion endpoint is strictly locked inside the workspace intranet with ephemeral pipeline tokens, while containers are recycled daily. cnb2api runs inside the workspace, converts it into a standard public API with zero dependencies, and leverages a v5.2 dual-watchdog self-healing architecture to deliver permanent domain access and 7×24 HA.

Why cnb2api?

Key Features

• 💰 Up to 200M Free DeepSeek Tokens Monthly:
  • Fully unleashes the 500~1,166 monthly AI Credits provided for free by CNB.
  • Native 30x Prompt Cache discount on upstream completions. In typical coding assistant, Claude Code, and multi-turn Agent scenarios with high prompt reuse, effective capacity reaches ~200M tokens/month.
• ⚡ Native Dual-Protocol Support:
  • OpenAI Compatible: /v1/chat/completions and /v1/models, supporting SSE streaming and faithful non-streaming aggregation (reconstructing usage, exact credit costs, incremental tool_calls, and finish_reason).
  • Anthropic Compatible: /v1/messages and /v1/messages/count_tokens, enabling Claude Code CLI direct connection with full support for thinking blocks, tool calling, and event streams.
  • 🛡️ Outbound Neutralizer: Transparently rewrites Claude Code internal billing headers and signature prompt phrases, eliminating false-positive 11128 upstream blocks without altering semantics.
• ♻️ v5.2 Zero Long-Lived Credentials + Self-Healing HA:
  • Zero Token Leakage: No static long-lived platform tokens in the workspace. The self-healing cron pipeline uses ephemeral platform CNB_TOKENs minted on demand and destroyed on completion.
  • Dynamic Routing Follower: On boot, start.sh registers the new dynamic subdomain to your relay (/ops/register), which hot-reloads nginx upstream configurations. Client URLs and keys stay permanent. Full recovery takes ~2m 13s.
  • Dormancy Watchdog: Circumvents CI platform cron dormancy (CNB pauses crons if no commits occur over multiple days). An external watchdog (cnb-watchdog.sh) detects stalled states and silently triggers fallback OpenAPI starts with cooldown protection.
• 🪶 True Zero Dependencies: 100% built on Node.js 22+ native primitives (fetch, ReadableStream, crypto.timingSafeEqual, node:test). Zero npm install, instant cold starts.
• 📊 Monitoring & Quota Dashboard:
  • cnb2api-quota CLI: One-command ANSI progress bar dashboard showing AI credits, dev core-hours, CI core-hours, and in-flight amounts directly from the official charge API. Supports --json and --line.
  • In-memory GET /usage accounting endpoint grouped by boot generation with UTC+8 daily rollups.

How It Works

Client (OpenAI Client / Claude Code / API Gateway)
  │  https://ai.example.com/v1 (Fixed domain, self-hosted Nginx relay)
  ▼
https://<dynamic-subdomain>-9001.cnb.run (CNB port-proxy, auto-synced via /ops/register on boot)
  │
  ▼
node src/server.mjs (Workspace port 9001, cnb2api reverse proxy)
  │  Bearer CNB_TOKEN (Auto-minted by CNB pipeline, internal network)
  ▼
https://api.cnb.cool/<org>/<repo>/-/ai/chat/completions (Official AI core endpoint)

The workspace is treated as cattle, not a pet:

1. Cron Recovery: An internal cron pipeline (*/5 * * * *) checks workspace health and calls workspace/start if stopped.
2. Auto-Registration: On boot, deploy/start.sh POSTs the newly assigned subdomain to /ops/register on your relay, which reloads Nginx.
3. External Fallback: An external VPS watchdog (cnb-watchdog.sh) monitors the fixed domain to guard against CI platform cron dormancy.

Quickstart

Three simple steps, only one API key to configure:

1. Fork Private: Fork this repository as a private repo on CNB.
2. Configure API Key: In .cnb.yml, set your custom PROXY_KEY in the env: block (e.g. openssl rand -hex 24).
3. Launch Cloud Workspace: Click "Start Cloud Development" on CNB. The build log prints PROXY_URI=https://<subdomain>-9001.cnb.run — ready to use!

💡 Need a permanent domain? Set up a simple Nginx reverse proxy on your VPS with /ops/register. See the Full Setup Guide (docs/SETUP.md).

Client Integration Examples

1. Claude Code Direct Connect (Anthropic Protocol)

ANTHROPIC_BASE_URL=https://ai.example.com \
ANTHROPIC_AUTH_TOKEN=your-proxy-key \
ANTHROPIC_MODEL=deepseek-v4-flash \
claude -p "Hello! Introduce yourself."

2. OpenAI Clients & Gateways

Point BaseURL to https://ai.example.com/v1 and set API Key to PROXY_KEY:

• Chat Apps: NextChat, LobeChat, Cherry Studio, Open WebUI
• Gateways: New API, One API (Channel type: OpenAI, model: deepseek-v4-flash)
• Coding Agents: Cursor, Continue, Codex CLI

3. curl Verification

curl https://ai.example.com/v1/chat/completions \
  -H "Authorization: Bearer your-proxy-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hi"}],"stream":false}'

Quota & Cost Estimates: How to Get 200M Tokens Free Monthly

Real production billing data measured over months of live operation (not marketing hype):

💡 The Math Behind 200M Free Tokens/Month:

1. Base Upstream Rate: Live measurements on deepseek-v4-flash show an uncached 9,000-token request costs ~0.39 credit (approx 23,000 tokens / credit).
2. Official Prompt Cache 30x Discount: Once prompt prefixes hit CNB's prompt cache, cost drops to ~0.01 credit, slashing cost to 1/30 of base price (~700,000 tokens / credit).
3. Real-World Scenarios: In coding assistants, Claude Code, and multi-turn Agent conversations with long system prompts and history reuse, cache hit rates typically sit at 80%~95% (assuming a realistic 90% cache hit rate): $$\text{Blended Cost} = 10% \times 1 + 90% \times \frac{1}{30} \approx 13% \text{ base cost} \implies \approx 177,000\text{ tokens / credit}$$ $$\text{Monthly Total} = 1,166\text{ credits} \times 177,000\text{ tokens} \approx \mathbf{206\text{ Million tokens / month}}$$
4. Run npm run quota anytime in your terminal to inspect your live remaining credits and consumption.

Quota Dashboard (CLI)

Check your quota and usage straight from the terminal, even if the proxy workspace is offline:

npm run quota                 # or: npx cnb2api-quota

  ◆ CNB quota  your-org

  Credits  ███████▋───────────────────  32%   320.0 / 1,000.0 cr
  Dev      ██████▏─────────────────────  25%   406.4 / 1,600.0 core-h
  CI       █▋──────────────────────────   8%   13.0 / 160.0 core-h

  in-fligh