Docs menu

Reference

Running CLI yourself

Understand the parts of a CLI platform, configure it, check it's safe for real money, and take it from staging to mainnet.

Explain it

CLI's code includes the whole platform, so you can run your own copy for your company or customers. This page is for those operators: what the parts are, the settings, and the checks before launch.

Do you need this page? Only if you're running your own CLI platform. If you use clicloud.app, none of this is needed.

CLI's code includes the whole platform: the API and dashboard, the worker that runs containers, the edge router configuration and the database schema. This page is for operators who run their own copy. It covers what the platform consists of, the important settings, the launch checks, and what still needs verifying on real infrastructure.

What the platform consists of

PartWhat it does
API replicasEvery replica serves the REST API, the dashboard at /, the skill file and the MCP gateway. None of them has the Docker socket
The leaderOne replica that holds a lease row in the database and runs background work: metering, cron, health checks, queues, stream settlement, deposit scanning, receipts, abuse scans, HA checks, GPU waitlist offers and image cleanup. If it stops, another replica takes over within 30 seconds
The workerThe only process with the Docker socket (npm run worker). It builds and runs containers under gVisor and only accepts HMAC-signed requests from the API (±60 seconds clock skew, replay cache). Builds can go to separate build machines
TraefikThe edge. Routes apps, checks paid routes and MCP paths with CLI before letting requests through, and issues certificates (optionally one wildcard through a DNS challenge)
The databasePostgres for production and for more than one replica; SQLite works for a single server. Migrations run on start
Blob storageAn S3-compatible bucket for backups and uploaded code

deploy/docker-compose.yml runs Traefik, the API (cli), the worker, the marketing site and Postgres on one host, with the API set to CLI_RUNTIME=remote so it talks to the worker. deploy/host-setup.sh prepares an Ubuntu host: Docker, gVisor, BuildKit, Railpack, the app network and firewall rules.

Setting up a host

  1. Take a fresh Ubuntu server with a public IP. Point your console hostname and a wildcard *.<app domain> at it.
  2. Run sudo deploy/host-setup.sh.
  3. Copy .env.example to deploy/.env and fill it in (see the settings below).
  4. Run cd deploy && docker compose up -d.
  5. Run npm run preflight with the same environment, and fix anything it fails.

For two machines (one control plane, one worker), follow deploy/STAGING.md.

Settings

All settings are environment variables. The groups below are the important ones; src/config.ts and src/token/config.ts have the complete list with defaults.

Core

VariableMeaning
CLI_SECRET_KEYMaster key (hex). Required
CLI_PUBLIC_URLPublic base URL of the API (https://…)
CLI_DASHBOARD_URLDashboard base URL, if different from the API
CLI_AUTH_DOMAINHost named in wallet sign-in messages (Sign-In with Ethereum). Defaults to the dashboard's host; a request from the dashboard's or API's own page uses that page's host
CLI_COOKIE_DOMAINCookie domain when the dashboard and API are on sibling subdomains
CLI_DATABASE_URLpostgres://… URL, or a SQLite file path
CLI_RUNTIMEremote (workers, recommended), docker (this process drives Docker) or fake (simulated)
CLI_WORKER_URL, CLI_WORKER_SECRETThe worker's address and the shared signing secret
CLI_BUILD_WORKER_URLOptional separate build worker
CLI_APP_DOMAINDomain apps are served under
CLI_REPLICA_URLHow other replicas reach this one (for tunnel relays)
CLI_OPERATORSComma-separated operators (email:[email protected], github:<id> or wallets). They're admins: they can do everything at /operations, including giving other people a narrower operator role (see Operator roles)
CLI_S3_BUCKET, CLI_S3_REGION, CLI_S3_ENDPOINT, CLI_S3_ACCESS_KEY_ID, CLI_S3_SECRET_ACCESS_KEYBlob storage for backups and uploads
CLI_KMS_KEY_ID (or CLI_VAULT_ADDR, CLI_VAULT_TOKEN, CLI_VAULT_KEY)Wraps each project's data key, and the key of every database backup (see Backups are encrypted)
RESEND_API_KEY, CLI_EMAIL_FROMSign-in and notification email
CLI_TRAEFIK_METRICS_URLTraefik's Prometheus endpoint, for request metrics, canaries and autoscaling
CLI_RPC_URLSRPC providers per chain, e.g. {"8453": ["https://…", "https://…"]}
CLI_SERVERS, CLI_GPU_PRICESExtra regions (each running a worker) and GPU prices per hour by kind
CLI_ANTHROPIC_API_KEY, CLI_LLM_MODELModel for fix-it PRs, the on-call agent and ask
CLI_WILDCARD_CERT_RESOLVEROne wildcard certificate for every app
CLI_RECEIPTS_KEY, CLI_RECEIPTS_CHAINKey and chain for anchoring audit-log receipts

Limits you may want to tune include CLI_API_RATE_PER_MIN (600 requests a minute per key or session; 0 turns the limit off), CLI_API_RATE_ANON_PER_MIN (120 per address without one), CLI_HEALTH_FAILURES (3), CLI_DEPLOYS_PER_HOUR (30), CLI_UPLOAD_MAX_MB (100), CLI_BACKUP_RETENTION_DAYS (7) and CLI_CPU_ABUSE_MINUTES (30 on real machines, off with the simulated runtime). An operator lifts a hold with POST /v1/admin/projects/:id/lift-hold, the button on the project page, or scripts/review.ts clear <projectId>.

Payments

VariableMeaning
CLI_TREASURYBase treasury address; turns on USDC on Base
CLI_NETWORK, CLI_USDC_ADDRESSNetwork (default Base Sepolia, eip155:84532) and USDC contract
CLI_SOLANA_TREASURYSolana treasury; turns on USDC on Solana
CLI_SOLANA_NETWORK, CLI_SOLANA_USDC_MINT, CLI_SOLANA_FEE_PAYER, CLI_SOLANA_RPCSolana network, mint, fee payer and RPC
CLI_FACILITATOR_URLLeave unset for the default; mock for local work with no chain (refused with a mainnet network: the server won't start)
CLI_CDP_KEY_NAME, CLI_CDP_KEY_SECRETCoinbase Developer Platform key: the mainnet facilitator and card onramp
CLI_PAYWALL_FEE_BPSPlatform fee on earnings (250 = 2.5%)
CLI_DEPOSIT_XPUB, CLI_DEPOSIT_CHAIN, CLI_DEPOSIT_CONFIRMATIONSPer-project deposit addresses
CLI_OUTBOUND_KMS_KEY_ID (or CLI_OUTBOUND_KEY), CLI_OUTBOUND_FEE_BPSWallet and fee for apps paying other x402 APIs

At least one of CLI_TREASURY or CLI_SOLANA_TREASURY is required. With a mainnet network, CLI uses Coinbase's facilitator (signed with the CDP key) and refuses the x402.org facilitator, which only settles testnets.

Payouts

VariableMeaning
CLI_PAYOUT_KMS_KEY_ID, AWS_REGIONAWS KMS signing key for withdrawals and refunds on Base (preferred: the key never leaves KMS)
CLI_PAYOUT_KEYA raw key instead (testnets only)
CLI_PAYOUT_SOLANA_KEYPayout key for Solana
CLI_PAYOUT_MIN_USDSmallest withdrawal (default 5)
CLI_PAYOUT_REVIEW_OVER_USDWithdrawals over this wait for an operator (default 500)
CLI_KYC_OVER_USDWithdrawals past this total need a verified identity

GitHub and Stripe

VariableMeaning
CLI_GITHUB_APP_ID, CLI_GITHUB_APP_SLUG, CLI_GITHUB_PRIVATE_KEY, CLI_GITHUB_CLIENT_ID, CLI_GITHUB_CLIENT_SECRET, CLI_GITHUB_WEBHOOK_SECRETGitHub sign-in, repo linking, push deploys and previews
STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRETCard top-ups, saved cards for automatic top-ups, and identity checks. Point a Stripe webhook at /v1/stripe/webhook with the events checkout.session.completed, checkout.session.async_payment_succeeded, payment_intent.succeeded, payment_intent.payment_failed, charge.refunded, charge.dispute.created and the identity.verification_session.* events
CLI_CARD_FEE_BPS, CLI_CARD_FEE_FIXED_CENTS, CLI_CARD_MIN_USD, CLI_CARD_MAX_USDCard fee and limits (defaults 290, 30, 5, 500)

Both are optional. Without them, those endpoints answer FEATURE_DISABLED.

CLI token

Off unless CLI_TOKEN_ADDRESS is set. Then you also need CLI_TOKEN_CHAIN, CLI_TOKEN_RPC_URL, CLI_TOKEN_ORACLE, CLI_TOKEN_CREDIT, CLI_TOKEN_STAKING and CLI_TOKEN_START_BLOCK; for the price keeper, CLI_TOKEN_POOL_MANAGER, CLI_TOKEN_POOL_ID, CLI_TOKEN_ETH_USD and CLI_TOKEN_KEEPER_KMS_KEY_ID (or CLI_TOKEN_KEEPER_KEY on testnet). CLI_TOKEN_CONFIRMATIONS (5) sets how many blocks before a purchase counts, and CLI_TOKEN_STAKING_DAILY_CAP_USD caps staking credit per day.

CLI_TOKEN_BENEFITS sets what each staking tier unlocks, as a JSON list in tier order:

JSON
[
  {"feeBps": 200, "priorityBuilds": false, "gpuPriority": false},
  {"feeBps": 150, "priorityBuilds": true, "gpuPriority": false},
  {"feeBps": 100, "priorityBuilds": true, "gpuPriority": true},
  {"feeBps": 50, "priorityBuilds": true, "gpuPriority": true}
]

Those are the defaults: a lower fee on what the project sells, its builds ahead in the queue when build slots are busy, and priority on the GPU waitlist. See The CLI token.

Chat approvals

VariableMeaning
CLI_SLACK_SIGNING_SECRETSigning secret of a Slack app whose interactivity URL is /v1/integrations/slack/interactive
CLI_DISCORD_PUBLIC_KEYPublic key of a Discord application whose interactions endpoint is /v1/integrations/discord/interactions

With either set, approval requests sent to Slack or Discord channels made from that app's webhooks get Approve and Deny buttons. People link their chat account to CLI once, from a link CLI sends them privately. Only owners and admins can decide, and only spending and production requests can be approved from chat; deletes and commands always go to the approval page. Owners can turn chat approvals off in the project's rules. See Approvals.

Edge outcomes

VariableMeaning
CLI_EDGE_ACCESS_LOGPath to Traefik's JSON access log, read by the leader (set in the compose file)
CLI_EDGE_TOKENShared secret for POST /v1/edge/outcomes, if you ship the log instead

For the refund guarantee, CLI needs to know how each guaranteed paid call went. Calls through CLI's MCP gateway are seen directly. For calls through the edge, the compose file turns on Traefik's JSON access log (keeping only the X-Cli-Receipt header), puts it on a volume shared with the API, and sets CLI_EDGE_ACCESS_LOG; the leader reads new lines every 10 seconds. On another setup, either do the same or ship the log to POST /v1/edge/outcomes with Authorization: Bearer $CLI_EDGE_TOKEN. Each line needs the receipt (request_X-Cli-Receipt) and the status (DownstreamStatus), or {"receipt", "status"}; up to 5,000 lines per request. A 5xx refunds the call; a receipt nobody reports on within 10 minutes is kept. See Refunding failed calls.

Build slots

VariableMeaning
CLI_MAX_CONCURRENT_BUILDSHow many deploys run at once (default 0: no limit)

When all slots are busy, deploys wait in line; projects whose staking tier includes priority builds go first.

Welcome credit

VariableMeaning
CLI_WELCOME_CREDIT_USDFree credit, in dollars, on a person's first project. Unset or 0 turns it off
CLI_WELCOME_CREDIT_DAILY_USDThe most welcome credit given out in any 24 hours (default 250)
CLI_WELCOME_CREDIT_WALLETStrue to give it to wallet-only accounts too (default false)

Each person gets it once. People who sign in with email or GitHub qualify; wallets only with CLI_WELCOME_CREDIT_WALLETS=true, since wallets cost nothing to make. Once a day's cap is reached, new projects start without it. See Credit, pricing and billing.

Public stats

VariableMeaning
CLI_PUBLIC_STATStrue serves a few headline numbers at GET /v1/stats without a token (default false)

The public numbers are deploys and the share made by agents over 30 days, active projects over 30 days, and agents at work over 7 days. Your full numbers are on the Operations page either way. See Usage numbers for operators.

Agent credentials

VariableMeaning
CLI_CREDENTIAL_SEED32 bytes of hex to sign agent credentials with. Unset: a key derived from CLI_SECRET_KEY

Agent credentials are signed with an Ed25519 key, published at /.well-known/jwks.json. Changing the seed (or CLI_SECRET_KEY while the seed is unset) changes that key, and credentials already issued stop verifying. See Agent credentials.

Your own cloud

VariableMeaning
CLI_BYOC_FEE_BPSWhat compute on a customer's own server costs, as a share of the usual rate (default 1500 = 15%; 0 to 10000)

Customers' workers connect out to /v1/workers/connect on your public URL, so the API must accept WebSocket upgrades there. Cloud-init on their machines downloads deploy/host-setup.sh from /v1/byoc/host-setup.sh, which answers NOT_FOUND if the file isn't in the API's working directory. See Run in your own cloud.

Security and audit

VariableMeaning
CLI_HOME_REGION, CLI_REGION_STORAGE, CLI_REGION_NAMESThe control plane's region (default us), backup storage for other regions, and names for region codes. A region opens for projects once it has servers in CLI_SERVERS and storage (see /docs/regions)
CLI_CANARY_KEY, CLI_CANARY_PROJECT, CLI_CANARY_EVERY_MINThe scheduled canary run against this server, and the status page it feeds (see /docs/staging)
CLI_DRILL_EVERY_DAYS, CLI_DRILL_DATABASE_URLAutomatic restore drills of CLI's own backups (default every 7 days) and an optional scratch database to restore into
CLI_HOLD_NEW_LISTINGSfalse lets new sellers' first Paid API listings show without review. Listings that trip an automatic check always wait (default true). Review them at /operations, Paid API listings
CLI_DEFAULT_BUDGET_USDThe monthly spending cap each new project starts with, in USD (default 25; 0 for none). Owners change it on the project's Usage and credit tab
CLI_DEFAULT_BUDGET_ACTIONWhat reaching that cap does: stop stops the project's services until next month or until the cap is raised (default), alert only sends a notice
CLI_REVIEWER_LOGINSPassword sign-in for app-directory reviewers, email:scrypt$… (comma-separated). Make a hash with npx tsx scripts/reviewer-password.ts <password>. Off when empty
CLI_OPENAI_APPS_CHALLENGEThe domain-verification token from OpenAI's portal, served at /.well-known/openai-apps-challenge
CLI_REQUIRE_OPERATOR_2FAtrue makes every operator-only route answer MFA_REQUIRED to an operator without a second factor (default false)
CLI_AUDIT_RETENTION_DAYSHow long the audit log, flight recorder, operator actions, sign-ins and second-factor changes are kept (default 90, at least 30; 400 or more for a SOC 2 Type II period)
CLI_SESSION_IDLE_MINUTESSessions unused for this many minutes end (default 0: sessions end only after their 24 hours). 120 is a reasonable start
CLI_BUILD_SANDBOXon (default) gives every build its own throwaway, rootless BuildKit on the cli-build network, which can't reach cloud metadata or private addresses. off goes back to one shared, privileged builder: don't. CLI_BUILD_SANDBOX_IMAGE, CLI_BUILD_NETWORK, CLI_BUILD_MEMORY_MB and CLI_BUILD_CPUS tune it
CLI_UNWRAP_ALERTEmail operators when this many different projects' secret keys are opened within 10 minutes, the shape of a bulk secret read (default 250; 0 turns it off)
CLI_SECRET_KEY_PREVIOUSOlder master keys, comma-separated, while a rotation is under way. Values sealed with them still open, and the leader moves them onto CLI_SECRET_KEY in the background. Remove once the Operations page says everything uses the new key
CLI_DERIVATION_KEYThe key long-lived, customer-visible values are derived from (app sign-in signing keys, provenance and agent credential keys, refund, telemetry, MCP and payment tokens). Unset: CLI_SECRET_KEY. Set it to the old key on a planned rotation so customers notice nothing
CLI_REQUIRE_OPERATOR_PASSKEYtrue: operators need a passkey, and confirm changes with it
CLI_ADMIN_ALLOW_IPSOperator routes answer only from these addresses or ranges (comma-separated). Empty: anywhere
CLI_OPERATOR_TWO_PERSON, CLI_OPERATOR_SOLO_CREDIT_USDThe two-person rule (on unless off): adding or removing operators, approving withdrawals and manual credit above the solo amount (default $100) need a second operator
CLI_TRIPWIRES, CLI_TRIPWIRE_VALUESTripwire secrets planted on start (off to skip), plus outside canary tokens as NAME=value;…. Using one alerts every operator
CLI_PAYOUT_NEW_ADDRESS_HOLD_HOURS, CLI_PAYOUT_PROJECT_DAILY_USD, CLI_PAYOUT_PLATFORM_HOURLY_USDWithdrawals to new addresses wait (48 hours), more than $2,500 a day from one project goes to review, and past $10,000 an hour across CLI everything waits for an operator
CLI_WORKER_IMAGEThe worker image customers' servers run, pinned by digest (ghcr.io/clicloud-app/cli@sha256:…)
CLI_SECURITY_CONTACTWhere /.well-known/security.txt sends vulnerability reports (default [email protected])
CLI_UNWRAP_HARD_STOPtrue also refuses to open more keys until those 10 minutes pass. Apps already running keep working

npm run preflight warns while any of these is below what an audit expects. See Access reviews and 2FA rules and SOC 2 readiness.

Hardening, and the emergency switches

deploy/SECURITY.md is the hardening guide: how a build escape, an over-trusted credential, a cloud identity mistake and a bulk decryption chained together at another platform in October 2026, and what CLI does and what you must configure so none of those steps works here. Read it before launch.

The worker holds the Docker socket and runs tenants' builds, so it must not see the control plane's keys: it refuses to start if CLI_SECRET_KEY, the database URL, Stripe, KMS or GitHub App keys are in its environment. In deploy/docker-compose.yml it has its own variables and isn't on the database network.

The Operations page is the admin panel, in tabs by role: Overview (people, projects, apps, deploys, servers and, for finance and admins, money, with daily charts and the latest failures), People (find anyone by email, wallet or project, see their projects and sign-ins, suspend, add credit or sign them out), Security (emergency switches, the master key, incidents, operators, access reviews and compliance evidence), Money, Moderation and Platform. A banner on every tab says when builds or sign-ups are paused or a key rotation is unfinished. Rotating CLI_SECRET_KEY is in deploy/SECURITY.md.

For an incident, admins have break-glass switches on the Operations page and in the API: pause all builds, pause new sign-ups, and end every session, connector token, API key and GitHub link at once (PUT /v1/admin/emergency, POST /v1/admin/emergency/revoke). They take effect on every replica within seconds, and each use is in the operator-action log.

Operator roles

Everyone in CLI_OPERATORS is an admin, and changing that list means changing the environment and restarting. Admins can give other people a narrower role from the Operators panel on the Operations page, or with PUT /v1/admin/operators:

RoleCan
supportThe abuse queue, Paid API listing review, platform checks and status page incidents, suspensions and appeals, and reading the cluster status and the backups list
financePayout reviews, the CLI token view and assigning token purchases, and the traction numbers
adminEverything, including taking backups, running restore drills, the benchmark, compliance evidence, security incidents, operator access reviews and the operator list

Those roles are kept in CLI's database, with who added each person and when, and each change is in the operator-action log. Keep CLI_OPERATORS to the few people who must always be able to get in. See SOC 2 readiness.

Backups are encrypted

Customers' database backups and the daily backups of CLI's own database are encrypted before they leave the machine, each with a fresh AES-256-GCM key wrapped by the key provider: AWS KMS (CLI_KMS_KEY_ID) or Vault if you set one, otherwise CLI_SECRET_KEY. Restoring needs access to that provider. To decrypt a backup of CLI's own database for a restore by hand:

Terminal
npm run backup:decrypt -- ./cli.pgdump.enc ./cli.pgdump

Run it with the server's environment (CLI_SECRET_KEY, or CLI_KMS_KEY_ID with AWS credentials allowed to decrypt, or the Vault settings). It doesn't need the database. deploy/RESTORE.md walks through the rest. If the key is lost, the backups can't be read.

The agent benchmark

Operators publish benchmark runs to the public leaderboard with npm run benchmark:publish. See The agent benchmark.

Launch check: npm run preflight

Terminal
npm run preflight

Run it with your production environment. It reports each check as pass, warn or fail, and exits non-zero if anything would be unsafe with real money. On a testnet it may warn but must not fail; on mainnet it must print Ready. with no failures.

It checks, among other things:

  • the networks, and that the facilitator settles each one (not the in-process mock);
  • the public URL is https;
  • operators are set;
  • the runtime uses workers (the API holds no Docker socket), and containers run under gVisor;
  • the database is Postgres;
  • project secrets are wrapped by AWS KMS or Vault, not the master key alone;
  • storage is off-host (S3);
  • payouts sign through KMS, identity checks are on, and the outbound wallet uses KMS;
  • the CLI token's RPC, keeper, price source and staking cap, when the token is on;
  • email is configured, and RPC providers are set for every EVM network.
  • operators must have a second factor, sessions have an idle timeout, and audit entries are kept long enough for an audit (all warnings only).

End-to-end check: npm run e2e

Terminal
CLI_E2E_API=https://staging.example.com CLI_E2E_TOKEN=<token from cli login> npm run e2e

It deploys the apps in examples/ on your real infrastructure, round-trips a database and rotates its password, uses a bucket, a queue and a tunnel, seals a receipt, then cleans up. It writes e2e-report.md and exits non-zero if any step failed.

VariableMeaning
CLI_E2E_PAYER_KEYA funded testnet wallet: also runs a real x402 top-up
CLI_E2E_GPUA GPU kind, such as L4: also deploys onto a GPU
CLI_E2E_ONLYRun only some steps, e.g. deploy,db
CLI_E2E_KEEP1 leaves the project for you to inspect

Run it after every infrastructure change and before every release. For a quicker check after each deploy, and on a schedule, use the smoke test (npm run smoke, see /docs/staging). npm run evals separately runs real models through the MCP tools on scripted scenarios against a simulated CLI.

From staging to mainnet

deploy/STAGING.md walks through it, and Staging and launch checks covers the smoke test, the CLI token on testnet and checking own-cloud servers and compliance. In short:

  1. Testnet stack. Two servers (control plane and worker), managed Postgres, an S3 bucket, AWS KMS keys, a CDP key, RPC endpoints and Resend. Run with Base Sepolia, then npm run preflight (warnings allowed, no failures). Fund the payout wallet with testnet USDC.
  2. Check: npm run e2e with a testnet payer passes every step. Then by hand: withdraw earnings and watch the payout confirm, and send USDC to a deposit address and watch it credit.
  3. Agents against staging. Run npm run evals for the agents you plan to recommend, then point one at staging through the MCP server.
  4. Mainnet, small. Switch to Base mainnet, leave CLI_FACILITATOR_URL unset, set CLI_PAYOUT_REVIEW_OVER_USD=50, and fund the payout wallet with only what you're prepared to lose. npm run preflight must print Ready.
  5. Check: a 1 USDC top-up, one paid route call, a 5 USDC withdrawal, a 5 USDC deposit and a card onramp purchase each show up once in the ledger, the statement and on chain. Restore last night's backup into a scratch database (deploy/RESTORE.md).
  6. Open the doors after an external security review and legal advice. Raise the review threshold once a week of payouts has gone through cleanly.

For SOC 2 readiness (the evidence export, restore drills, /health/deep for an outside uptime monitor and the compliance/ kit), see SOC 2 readiness.

Not yet verified on real infrastructure

These work in tests but depend on your machines. npm run drills checks most of them on your server (see /docs/staging): failover, point-in-time recovery, restores of each engine, sandboxes under gVisor, and paid routes and metrics through Traefik. Check the rest by hand:

  • Redis and MongoDB restores bring the data back (the drills check that they finish, not the data).
  • The directory's try console charging through Traefik (the drills check paid routes directly).
  • Live traffic on the canvas, which needs Traefik metrics.
  • For the CLI token: the Uniswap v4 pool storage slot on Robinhood Chain, Chainlink ETH/USD availability there, and Cancun opcode support.

Also known: the shared sandbox terminal shows a command's output when it finishes rather than streaming it.