Skip to content

README.md

Latest commit

 

History

History
96 lines (65 loc) · 4.94 KB

README.md

File metadata and controls

96 lines (65 loc) · 4.94 KB
Raw

CodeBuddy2API

CI codecov

Proxy CodeBuddy with OpenAI-compatible and Anthropic-compatible APIs for Codex, Claude Code, and standard SDK clients.

CodeBuddy2API

CodeBuddy2API is a self-hosted gateway with a web-based admin console for managing credentials, access keys, usage, account status, debug traces, and runtime settings. The console is a progressive web app, so a browser can install it as a desktop or home-screen app.

This project is a substantial refactor of Sliverkiss/CodeBuddy2api, with a redesigned admin console, multi-protocol API support, and flexible storage backends.

Quick Start

The following command starts a single-instance deployment with SQLite:

docker run -d \
  --name codebuddy2api \
  --restart unless-stopped \
  -p 8001:8001 \
  -v codebuddy2api-data:/app/.codebuddy_data \
  -e CODEBUDDY_STORAGE_BACKEND=sqlite \
  -e CODEBUDDY_STORAGE_ENCRYPTION_KEY='replace-with-a-long-random-secret' \
  -e CODEBUDDY_STORAGE_IMPORT_LEGACY_FILES=false \
  ghcr.io/orangeboychen/codebuddy2api:latest

Open http://127.0.0.1:8001/dashboard, complete CodeBuddy authentication or add a credential manually, then create an access key for your clients.

Desktop App

Electron builds ship with every release — macOS (Apple silicon and Intel), Windows, and Linux (x86_64 and arm64):

Download the latest release

The app bundles the same gateway: it starts it on 127.0.0.1:8001 and opens the console in a native window. Data stays in Electron's userData directory, so there is nothing to configure. The macOS builds are signed and notarized, so the dmg opens on a double-click; on Windows, dismiss the SmartScreen prompt with Run anyway.

API Compatibility

The gateway exposes these endpoints under /v1:

  • POST /v1/chat/completions — OpenAI Chat Completions
  • POST /v1/responses — OpenAI Responses
  • POST /v1/messages — Anthropic Messages
  • GET /v1/models — models available to the requesting access key

Authenticate inference requests with either header:

Authorization: Bearer <access-key>
x-api-key: <access-key>

Example OpenAI-compatible request:

curl http://127.0.0.1:8001/v1/chat/completions \
  -H 'Authorization: Bearer <access-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<model>",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Storage

  • file — zero-configuration storage for a single instance
  • sqlite — encrypted SQLite storage for a single instance
  • pg — PostgreSQL storage for multiple instances

Database backends require CODEBUDDY_STORAGE_ENCRYPTION_KEY. Set DATABASE_URL for PostgreSQL or CODEBUDDY_STORAGE_SQLITE_PATH for SQLite.

Switching an existing file deployment to a database backend imports only config, admin auth, access keys, debug settings, and credentials. Usage events and debug traces are left behind, so export what you need from the console before switching.

Security Notes

  • /v1/* is unauthenticated until an access key exists. With no access key stored, inference requests are allowed through by design so a fresh instance needs no setup. Create an access key in the console before exposing the port beyond localhost.
  • At-rest encryption needs a database backend. The file backend stores credentials and access keys as plain JSON with 0600 permissions and ignores CODEBUDDY_STORAGE_ENCRYPTION_KEY entirely, so setting the key on a file deployment changes nothing. Move to sqlite or pg to get encryption — those backends refuse to start without the key.
  • Back up the passphrase and the database. Decrypting a document needs the CODEBUDDY_STORAGE_ENCRYPTION_KEY and the storage-crypto/kdf-salt row stored alongside it. A partial restore — passphrase without the database, or a namespace-by-namespace export that skips that row — leaves every encrypted credential and access key unreadable even with the right passphrase.
  • Do not roll back after the first write on a database backend. Documents written by this version use aes-256-gcm:v2, which older releases cannot decrypt; they fall back to the wrong key and fail on every credential and access key. The admin console still loads because admin auth is not encrypted, so a rollback looks healthy while /v1/* is broken. Roll forward, or restore the pre-upgrade database backup.

Documentation

Read the documentation

License

See LICENSE.