Self-hosting

Self-hosting

Run the Kaimei API on your own infrastructure, against SQLite on a laptop or Postgres for a team.

The API is a FastAPI service and runs anywhere Python 3.9 does, against SQLite for a laptop or Postgres (Supabase works) for a team. Enterprise plans include a private deployment; the configuration below applies to any installation.

Service 1.0.0 serves the /v1 contract: new fields may appear, and existing fields keep their meaning. See API compatibility. Rate limits are stored in the database, so every process of one deployment shares them. An analysis that was still running when the process stopped is resumed; after three interrupted attempts it fails and can be started again. Responses carry X-Request-Id.

Configuration is through KAIMEI_* environment variables or a .env file in the working directory. The ones that matter most:

VariableDefaultMeaning
KAIMEI_DATABASE_URLsqlite:///./kaimei.dbSQLAlchemy URL. Postgres in production.
KAIMEI_SECRET_KEY(dev value)HMAC key for session tokens. At least 32 random bytes; always set it.
KAIMEI_ENVdevelopmentproduction turns email verification on by default; test turns rate limits and quotas off.
KAIMEI_PUBLIC_API_URL / KAIMEI_DASHBOARD_URLlocalhostUsed for OAuth callbacks, verification and invitation links, CORS, the dashboard pages Stripe returns customers to, and the billing webhook's address, which must be https for Stripe to reach it.
KAIMEI_ALLOW_SIGNUPtrueSet false to stop self-serve sign-up, and create accounts with kaimei-api create-user. An invitation does not open sign-up: the person invited needs an account first.
KAIMEI_MAX_REFERENCE_ROWS5000Reference rows kept per model.
KAIMEI_EXPLANATION_EVAL_BUDGET60000Soft ceiling on model evaluations per explanation.
KAIMEI_IMAGE_EXPLAIN_SECONDS40Time budget image explanations plan their grid to fit.
KAIMEI_MAX_TENSOR_BYTES536870912Largest single binary tensor upload, compressed.
KAIMEI_REMOTE_INFERENCE_TIMEOUT_S30Default timeout for remote endpoints.
KAIMEI_BEHIND_CLOUDFLARE / KAIMEI_TRUST_PROXYfalseRead the client IP from CF-Connecting-IP / X-Forwarded-For for rate limits.
KAIMEI_TURNSTILE_* , KAIMEI_SMTP_*, KAIMEI_GOOGLE_* , KAIMEI_GITHUB_*unsetBot protection on sign-up; verification and invitation email (without SMTP an invitation link is returned to whoever sent it, to pass on); OAuth sign-in.
KAIMEI_STRIPE_SECRET_KEY / KAIMEI_STRIPE_WEBHOOK_SECRETunsetPaid plans through Stripe. Without a secret key the plans are listed and buying one is 503 billing_not_configured. Use a test-mode key (sk_test_…) anywhere but production.
KAIMEI_STRIPE_PRICE_STANDARD / _PRICE_TEAM / _PORTAL_CONFIGURATIONunsetOnly for prices or a portal configuration that kaimei-api billing setup did not make; it finds its own.
KAIMEI_STRIPE_AUTOMATIC_TAX / KAIMEI_STRIPE_PROMOTION_CODESfalseSales tax and VAT worked out by Stripe Tax at checkout, and a promotion-code field there.

Point the Python client at your installation with base_url or KAIMEI_BASE_URL; the dashboard with VITE_API_URL.

Paid plans. Set KAIMEI_STRIPE_SECRET_KEY, run kaimei-api billing setup to see what the Stripe account lacks, then --apply to create the plans' prices, the customer portal configuration and the webhook endpoint, and set KAIMEI_STRIPE_WEBHOOK_SECRET to the secret it prints. In Stripe, under Billing, Revenue recovery, keep cancelling the subscription as what happens when every retry of a payment has failed: a subscription left past_due keeps its plan. Enterprise is set by hand with kaimei-api billing set-plan.

Upgrading. Starting the API applies any database migration it has not recorded. The release that adds organizations gives every existing account an owner's membership of its own workspace, and nothing moves. An organization that already has more than one member and is not on Team becomes read-only, so put it on a plan first if it should keep working as it does: kaimei-api billing set-plan <slug> team.

shell
pip install -e ".[dev]"                 # from the kaimei API repository
kaimei-api init-db                      # create tables
kaimei-api seed-demo                    # demo@kaimei.ai / kaimei-demo, five reference models, an API key
kaimei-api serve --reload               # http://localhost:8000

# Paid plans: with KAIMEI_STRIPE_SECRET_KEY set
kaimei-api billing setup                # check the Stripe account; changes nothing
kaimei-api billing setup --apply        # create what is missing, print KAIMEI_STRIPE_WEBHOOK_SECRET
kaimei-api billing sync                 # read every subscription back from Stripe
kaimei-api billing set-plan acme-risk enterprise

# Postgres / Supabase
pip install -e ".[postgres]"
export KAIMEI_DATABASE_URL=postgresql://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:5432/postgres
kaimei-api migrate-db --inspect         # row counts in the local SQLite file
kaimei-api migrate-db                   # copy it over