A Pre-Deploy Checklist for CLIProxyAPI (CPA): Account Authorization, Admin Port and Key Isolation

I'd ask first: why not just use the official client

CLIProxyAPI can organize multiple CLI accounts and providers into a compatible API. It does save some client configuration, but it also adds a service that holds requests, auth files, routing rules and admin permissions long-term.

If you have one account and one client, the official entrance is usually simpler. CPA only starts to be worth it when multiple clients genuinely need a unified protocol, you're willing to maintain updates and backups, and you can protect the admin entrance.

Conversely, if the goal is just finding a "cheaper unlimited API," or you're about to open the admin page straight to the public internet, this architecture's risk outweighs the convenience.

As of this article's verification date, the official quickstart offers Homebrew, Linux, Windows, Docker and source-build paths. This round didn't install a new instance, import an OAuth account or open port 8317. What's discussed below is the official, verifiable structure and the deploy checks — not a run proof of a new instance.

Where CPA sits in the chain

Codex / Claude Code / compatible client
              |
        compatible API request
              |
          CLIProxyAPI
              |
    OAuth accounts / official API / upstream

CPA can unify the protocol and schedule accounts, but it can also see or handle:

• Client requests.
• The CPA API key.
• OAuth auth files.
• Upstream account status.
• Model and routing config.
• Admin operations.

So CPA isn't as simple as "swap a Base URL." It's a new point where credentials concentrate.

Four kinds of secret can't be mixed

The admin key

Used to enter CPA's admin capabilities. After a leak, an attacker could change config, view accounts or create client keys.

Client API keys

Handed to Codex, Claude Code or another compatible client. They shouldn't automatically have admin permission.

OAuth auth files

Represent upstream account authorization, usually higher risk than an ordinary client key. Don't pass them via chat, cloud drives or public repos.

Server login credentials

SSH keys, system passwords and cloud platform tokens maintain the host; they shouldn't go into CPA config.

The four kinds of credential must be rotatable and revocable separately. No log or backup should bundle them in plaintext into one file and send it to someone.

Choose local or VPS first

Running locally

Good for:

• Using it only on your own computer.
• Not needing cross-device.
• Not wanting to open a public port.
• Accepting that the service stops when the computer is off.

Listening on the local address by default is a lower-risk starting point.

Running on a VPS

Good for:

• Multiple devices needing access.
• The service needing to stay online.
• Being able to maintain HTTPS, firewall, updates and backups.
• Knowing how to restrict source IPs or use a private network.

A VPS isn't a synonym for more stable. It also means the admin port and auth files are exposed long-term on a public host.

For a first deploy, prefer local. Decide whether to migrate only after confirming a real need.

The macOS official quickstart

The current official docs provide:

brew install cliproxyapi
brew services start cliproxyapi

The docs also note that the Homebrew service's default config path and your home-directory config may differ. When the config path is unclear, the most common problem isn't that the program isn't installed, but that the service read a different config.

Before starting, confirm:

• The actual path of the current config file.
• The file owner and permissions.
• Where the auth directory is.
• Which user runs the service.
• Whether it still reads the same config after an upgrade.

Don't keep several config.yaml files and then guess which to edit.

A Docker deploy, watch three mounts

The official quickstart's Docker example includes:

• config.yaml.
• auth-dir.
• the plugins directory.

They carry different responsibilities:

config.yaml: service config.

auth-dir: OAuth and auth material.

plugins: extensions and their persistence.

Deleting the container doesn't mean these host files are deleted too; conversely, mount them wrong and a container restart may lose plugins or auth.

Don't mount your whole home directory into the container. Mount only the directories clearly needed, and set least-privilege file permissions.

Port 8317 can't directly equal the public entrance

A common move in reference tutorials is to open 8317 and then reach the admin page by IP.

That path works; it doesn't mean it suits long-term operation.

A safer order:

1. The service first listens only on localhost or a private network.
2. Confirm locally that the API and the admin entrance differ.
3. For remote access, use a VPN, an SSH tunnel or a controlled reverse proxy.
4. Configure HTTPS.
5. Restrict source addresses.
6. Don't expose the admin path to the whole public internet.
7. Check the logs don't output secrets.

A security group opening a port is only a network allow — not identity authentication.

One minimal local acceptance

After deploying, check at least:

• The process runs as the expected user.
• The listen address and port match the design.
• The admin page can't be reached without credentials.
• A client key can't call the admin API.
• With no account, the service doesn't fake success.
• A config error stops it clearly.
• After a restart it reads the same config.
• Logs hide OAuth, cookies and full keys.

You can use system tools to view listening ports, but don't put the public IP, account email and auth content into an article screenshot.

Ask six questions before importing an account

1. Is this account yours.
2. What is the OAuth authorization scope.
3. Do the upstream terms allow this use.
4. Where is the auth file stored.
5. How to revoke it after a leak.
6. Is the auth cleared along with CPA when deleted.

Don't buy cheap accounts, disposable accounts, shared accounts or auth files of unknown origin. Cheap isn't the only risk — the request content in the account may also be reachable by the original holder or the supply chain.

Multiple accounts isn't unlimited capacity

The official project supports multiple accounts and round-robin, but that doesn't mean you can ignore:

• Upstream rate limits.
• Account plan limits.
• The terms of use.
• Concurrent-login risk control.
• Cost attribution.
• Request failures and retries.
• Model differences.

The routing system has to keep the failure reason — it can't automatically read one account being limited as "just switch to the next."

Every retry can add cost or repeat an external action.

Plugins need separate review

CPA's plugins directory can change the service's capabilities. Before installing a plugin, check:

• The source.
• The version.
• The build script.
• Network access.
• Config reads.
• Key access.
• The update mechanism.
• How to uninstall.

A plugin persistence directory existing doesn't mean the plugin is trustworthy.

What a backup should cover

A minimal backup includes:

• The redacted config structure.
• The current version.
• How the service starts.
• The plugin list.
• The client config.
• The credential revocation list.

If OAuth files enter a backup, the backup itself must be encrypted and access-restricted. Don't push it to GitHub alongside ordinary project code.

A restore test should be done in an isolated environment, confirming you didn't accidentally start old credentials as a second online instance.

Updates and rollback

Before updating, record:

• The current version.
• The config file hash.
• The auth-directory backup.
• The client Base URL.
• The current listen port.
• A known working request.

After updating, verify with a minimal, non-sensitive input.

If it fails, rolling back the program version doesn't necessarily roll back the config format. Keep the pre-update config and migration notes — don't rely only on the latest image tag.

Before running long-term, re-check these

• You know why you need CPA.
• The local-vs-VPS choice was made deliberately.
• The admin key, client keys, OAuth and server credentials are separated.
• The admin entrance isn't directly exposed to the public internet.
• The config path is single and clear.
• The auth-dir permissions are controlled.
• Plugins were reviewed.
• Logs don't leak secrets.
• Backup and revocation paths exist.
• A client's minimal request gets the expected response.
• The upstream account and cost boundaries are clear.

CPA concentrates convenience and risk at the same time. Only when the admin entrance, client keys, OAuth files, backup and revocation paths can each be answered is it ready to move from local testing into a long-term service.