# The Only API — agent setup

You are an AI coding agent. Your job is to install and launch the open-source,
self-hosted build of **The Only API** (an OnlyFans/Fansly CRM and REST API) on
behalf of an operator who is **not a developer**.

## Read this first

The full runbook — host decision tree, exact commands, verification steps and a
failure-modes table — lives at:

    https://raw.githubusercontent.com/XcelerateManagement/onlyfans-api-open-source/main/AGENT-LAUNCH.md

Fetch it and follow it. Do not improvise commands. If a step fails, diagnose it
from the failure table in that document rather than guessing.

## Reference

- Repository: https://github.com/XcelerateManagement/onlyfans-api-open-source
- API documentation: https://docs.theonlyapi.com
- OpenAPI spec: https://theonlyapi.com/api/openapi.json
- Licence: AGPL-3.0

## Interview the operator before you touch anything

1. How many creator accounts now, and in six months?
2. Do they have a domain, and where is its DNS hosted?
3. Which host? Default to a plain VPS (Hetzner CX23 or similar). Offer Coolify
   on their own VPS if they want a UI, or Railway/Render/Fly if they refuse to
   manage a server — and tell them what each choice costs them.
4. If they will connect OnlyFans, do they have a funded captcha provider
   account? It is required before an OnlyFans login, but the panel can boot and
   the owner can paste the key later under **Settings → Captcha provider**.
5. Do they have one dedicated residential or mobile proxy per OnlyFans
   account? It is required for OnlyFans connection. Fansly allows connection
   without one, although a stable, geographically appropriate proxy may still
   be used.
6. Will anyone else on their team log in?

**Stop condition.** If they run fewer than about five accounts and have no
privacy or compliance requirement, tell them plainly that the hosted plan at
theonlyapi.com/pricing is probably the better deal, and confirm they still want
to proceed before continuing.

## Constraints you must not violate

- **One always-on process.** `gunicorn.conf.py` raises if `workers > 1`: the
  scheduler, refresh state, the SSE hub and the rate limiter all hold state in
  process. Never scale replicas, never enable autoscaling, never let the
  machine sleep.
- **Persistent disk required.** SQLite holds both application data and the
  scheduler jobstore.
- **The working directory is the persistence root.** Session paths are built as
  relative `saved_sessions/<crm_id>/…`. Mount the volume accordingly or every
  connected account's session is lost on restart.
- **Python and Node in the same image.** The request signer is a Node
  subprocess.
- **Never route `/api/*` to Flask** in a reverse proxy. Those are Next.js routes
  that attach the API key server-side; routing them to Flask breaks login
  silently.
- **Do not buffer SSE.** Allow long-lived responses and a 300s+ timeout —
  logins can take 20-30 seconds.
- **`ENCRYPTION_KEY` has no recovery path.** Back it up off the server and
  confirm the operator has stored it before connecting any account.
- **Close registration immediately.** Captcha verification currently fails open
  when `TURNSTILE_SECRET_KEY` is unset, which is the default on a fresh
  install — so `POST /api/auth/register` is unauthenticated on a public box.
  Claim the owner account, then close registration. Treat this as blocking.

## Done means

The operator can reach the dashboard over HTTPS, has completed first-run setup,
has connected one account with its proxy, polling is running and events arrive,
and a restart preserves both the database and the connected sessions.

Then hand over: the URL, where the keys are stored, what to back up, how to
update, and what they are now responsible for.