CLIProxyAPIHome

module
v1.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 19, 2026 License: MIT

README

Home

English | 中文

Home is a comprehensive credential management, scheduling, and distribution service designed for CLIProxyAPI.

It serves as a centralized hub for managing and scheduling API credentials in large-scale CLIProxyAPI cluster deployments. CLIProxyAPI nodes communicate with Home to retrieve necessary API credentials and report usage statistics.

Home and Home Management Center (HMC)

Home provides the backend service, and Home Management Center (HMC) provides a visual Web interface for Home. The two open-source projects are maintained separately. Official Home releases embed HMC so they can be deployed and updated together.

Deploying an official release

Official Home binaries and Docker images include the Web interface, so HMC does not need to be deployed separately. After starting Home, open its address, such as http://localhost:8327. The administrator console is at /management.html, and the user workspace is at /user.html.

Administrator access requires a management key; see the authentication instructions. Database setup and configuration import are covered under Cluster Mode. Update the Home binary or Docker image to update the bundled Web interface.

Developing both projects locally

For frontend development, clone both repositories into sibling directories and run Home and HMC in separate terminals. Environment requirements are listed in Home's go.mod and the HMC README.

For a new local setup without cluster.yaml, copy Home's config.example.yaml to config.yaml and set a non-empty management.secret-key. Import that configuration into the local SQLite database, then start Home in one terminal:

cd CLIProxyAPIHome
go run ./cmd/home -config config.yaml -import
go run ./cmd/home -addr 127.0.0.1:8327

An existing configured Home backend can be used directly.

Start HMC in another terminal:

cd Home-Management-Center
bun install --frozen-lockfile
bun run dev

Open http://localhost:3000/management.html, enter http://127.0.0.1:8327 as the management endpoint, and sign in with the management key. Frontend changes can be previewed without rebuilding Home.

Building and releasing the bundled frontend

To build Home with the Web interface from source, first build HMC, then copy the complete output into Home before compiling. Starting from the parent of the two sibling repositories:

cd Home-Management-Center
bun install --frozen-lockfile
bun run build:embedded
cp -R dist/. ../CLIProxyAPIHome/internal/managementasset/static/
cd ../CLIProxyAPIHome
go build -o CLIProxyAPIHome ./cmd/home

Home's source checkout does not include the generated frontend. Neither go build nor docker build builds HMC automatically, so prepare the complete frontend output before building either a binary or a Docker image.

Official releases automate this process: a version tag triggers the frontend build, followed by Home packaging and publication of binaries or Docker images. See the binary release workflow and Docker workflow for details.

Key Features

  • Scalable Node Management: Supports connecting an unlimited number of CLIProxyAPI nodes for credential distribution, ideal for large-scale deployments.
  • Multi-Provider OAuth2 Support: Manages OAuth2 credentials for various AI model providers, including OpenAI, Claude, Codex, Antigravity, Kimi, xAI, and more.
  • High Availability: Supports multi-account management and round-robin load balancing to ensure optimal performance and reliability.
  • Secure Access: Provides a streamlined CLI authentication flow to ensure secure access to APIs.
  • Plugin Support: Supports installing and enabling CLIProxyAPI-compatible plugins through Home Management.
  • Flexible Upstream Integration: Easily integrate upstream providers via configuration, including:
    • OpenAI-compatible providers (e.g., OpenRouter)
    • OpenAI Responses protocol providers
    • Anthropic Messages protocol providers
    • Google Gemini protocol providers

Cluster Mode

Home now always runs from a database-backed runtime. When cluster.yaml is absent, Home runs the same scheduler, node discovery, leader election, event watcher, management, and RESP logic on a local SQLite database. The default SQLite path is home.db; use -sqlite-path to override it.

When cluster.yaml exists, Home enables cluster mode and uses the database backend declared in that file. Copy cluster.sqlite.example.yaml or cluster.pgsql.example.yaml to cluster.yaml as a starting point. PostgreSQL accepts either individual connection fields or a connection string in pgsql.postgres_uri. PostgreSQL is recommended for multi-node deployments. SQLite is also supported, but cluster SQLite requires node.external-ip so other nodes and CPA clients can reach this node.

Set slow-query-threshold under the selected pgsql or sqlite backend to control slow SQL logging. It accepts Go duration strings such as "500ms" or "1s" and defaults to "200ms".

config.yaml and auth-dir are no longer runtime storage. They are import/export exchange formats only. To migrate an existing local setup into the database, run:

./CLIProxyAPIHome -import

By default, import reads ./config.yaml and then resolves credentials from the auth-dir value inside that config. Use -config <path> to select another config file, -auth-dir <path> to override credential discovery, and -sqlite-path <path> when importing into a non-default SQLite database. Import is idempotent, so rerunning it with the same files does not duplicate records.

To export config and credentials back to local files, run:

./CLIProxyAPIHome -export

Export writes ./config.yaml and credential files under ~/.cli-proxy-api/ by default. Use -export-dir <path> to write <path>/config.yaml and credential files under <path>/auths/. It refuses to overwrite an existing config.yaml or a non-empty credential directory at the selected target.

-export / -import preserve the legacy exchange format. API keys are exported only as their actual key values, so Home database-only metadata such as API key display names, user ownership, and channel/model-group bindings is not a complete backup. Use -db-export <snapshot.zip> and -db-import <snapshot.zip> for full database backup and restore. Database snapshot format v4 includes API key display names and cannot be imported by older Home versions. Before upgrading, retain a database backup or an older-version-compatible snapshot for rollback.

In cluster mode, the Management API operates directly on database data. The default listen port comes from node.port in cluster.yaml; the startup -addr flag can override the listen address. Set node.external-port when a reverse proxy changes the port that clients must use; when omitted, the advertised cluster node port follows the final listen port.

RESP password authentication has been removed. Home RESP access only accepts mTLS-authenticated clients; CPA should connect with -home-jwt or configured TLS material. allow-host is only an IP allowlist and is not a password mechanism.

Docker Compose uses docker-compose.sqlite.yml or docker-compose.pgsql.yml. Copy the matching cluster.sqlite.example.yaml or cluster.pgsql.example.yaml to cluster.yaml, then use /CLIProxyAPIHome/data/home.db for SQLite or postgres as the PostgreSQL host. Select either database type when importing existing local state:

COMPOSE_FILE=docker-compose.sqlite.yml
# PostgreSQL: COMPOSE_FILE=docker-compose.pgsql.yml
docker compose -f "$COMPOSE_FILE" run --rm \
  -v "$PWD/config.yaml:/CLIProxyAPIHome/config.yaml:ro" \
  -v "$PWD/auths:/root/.cli-proxy-api" \
  home ./CLIProxyAPIHome -import

Strict Credential Concurrency Limits

Before enabling credential concurrency policies, follow the strict credential concurrency limits deployment runbook. It defines the required SQLite and PostgreSQL topologies, certificate identity requirements, capability checks, and fail-closed mixed-version rollout.

Contributing

Issues, feature requests, and pull requests are welcome. Choose the repository that maintains the affected component:

  • Frontend / Web UI: Report page display and interaction issues in HMC Issues, and submit frontend changes to HMC.
  • Home backend: Report service, scheduling, and data management issues in CLIProxyAPIHome Issues, and submit backend changes here.

For changes spanning both projects, link the related issues or pull requests. Update the relevant Management API or User API documentation when an interface changes.

  1. Fork the repository.
  2. Create your feature branch (git checkout -b feature/amazing-feature).
  3. Commit your changes (git commit -m 'Add some amazing feature').
  4. Push to the branch (git push origin feature/amazing-feature).
  5. Open a Pull Request.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Directories

Path Synopsis
cmd
home command
internal
auth
Package auth provides authentication functionality for various AI service providers.
Package auth provides authentication functionality for various AI service providers.
auth/antigravity
Package antigravity provides the minimal constants needed to refresh Antigravity credentials.
Package antigravity provides the minimal constants needed to refresh Antigravity credentials.
auth/claude
Package claude provides token refresh functionality for Anthropic credentials used by the scheduler.
Package claude provides token refresh functionality for Anthropic credentials used by the scheduler.
auth/codex
Package codex provides authentication and token management for OpenAI's Codex API.
Package codex provides authentication and token management for OpenAI's Codex API.
auth/devin
Package devin provides OAuth helpers for Devin / Cognition credentials.
Package devin provides OAuth helpers for Devin / Cognition credentials.
auth/kimi
Package kimi provides token refresh for Kimi (Moonshot AI) credentials used by the scheduler.
Package kimi provides token refresh for Kimi (Moonshot AI) credentials used by the scheduler.
auth/meta
Package meta provides authentication and token management for Meta Muse (api.meta.ai).
Package meta provides authentication and token management for Meta Muse (api.meta.ai).
auth/oautherror
Package oautherror provides OAuth response diagnostics.
Package oautherror provides OAuth response diagnostics.
auth/xai
Package xai provides OAuth2 authentication helpers for xAI Grok.
Package xai provides OAuth2 authentication helpers for xAI Grok.
buildinfo
Package buildinfo exposes compile-time metadata shared across the server.
Package buildinfo exposes compile-time metadata shared across the server.
config
Package config provides configuration management for the CLI Proxy API server.
Package config provides configuration management for the CLI Proxy API server.
credentialweight
Package credentialweight defines shared credential weight validation and parsing.
Package credentialweight defines shared credential weight validation and parsing.
registry
Package registry provides model definitions and lookup helpers for various AI providers.
Package registry provides model definitions and lookup helpers for various AI providers.
util
Package util provides utility functions for the CLI Proxy API server.
Package util provides utility functions for the CLI Proxy API server.
watcher
Package watcher watches the config file and auth directory for changes and triggers hot reload callbacks.
Package watcher watches the config file and auth directory for changes and triggers hot reload callbacks.
watcher/synthesizer
Package synthesizer provides auth synthesis strategies for the watcher package.
Package synthesizer provides auth synthesis strategies for the watcher package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL