# Access, configuration and deployment sequence

Reviewed: 2026-09-07. Never send secret values in chat, committed files, browser bundles, screenshots, prompts or logs. Use your deployment secret store for production and ignored local `.env` files for development.

## What is already available

The connected Higgsfield MCP can inspect models, estimate credits, manage approved reference media and use the remote media sandbox. A read-only check succeeded. The only visible workspace is a private free workspace with zero credits; unlimited generation is unavailable. No credit was spent, trial activated or purchase made. The sandbox reports Python 3.11.6, Node 20.9.0 and ffmpeg 5.1.9; this is independent of CartoonOS's Python 3.14 backend.

MCP access in this conversation does not install an authenticated connector in your dashboard server. Higgsfield Cloud API credentials and web/MCP subscriptions may have different entitlements. Verify the exact account and billing surface before provisioning.

## Minimum input checklist

| Need | Provide / configure | Why / scope |
|---|---|---|
| Channel | URL, platform channel ID, existing published IDs | Establish identity and import actual history |
| Production envelope | Monthly cash ceiling + currency, maximum episode/shot spend, cadence, reviewer hours | Prioritize and enforce cost/capacity limits |
| Higgsfield | Confirm intended account and available paid credits | Current connected workspace cannot fund generation |
| Mascots | Location of original Lumi/Tiko binaries and rights records | Reference approval cannot rely on missing files or prose |
| Dashboard | Chosen domain, hosting account, owner sign-in identity | Private authenticated application and DNS |
| Storage + DB | Approved provider/project/region and scoped service credentials | Durable records, private media, backups |
| YouTube OAuth | Google Cloud project and authorized owner consent | Read private analytics; upload authorization is separate |

## Variable contract

The single source of truth for all environment variables across CartoonOS is the root `.env.example` file. Copy it to `.env` in the repository root to configure local development or prepare containerized deployment variables.

Current backend: `CARTOONOS_ENVIRONMENT`, `CARTOONOS_DATABASE_URL`, `CARTOONOS_REDIS_URL`, `CARTOONOS_TEMPORAL_TARGET`, `CARTOONOS_TEMPORAL_NAMESPACE`, `CARTOONOS_HIGGSFIELD_WORKSPACE_ID`, optional `CARTOONOS_OTLP_ENDPOINT` and `CARTOONOS_SENTRY_DSN`.

Future server-side integrations: `HF_API_KEY_ID`, `HF_API_KEY_SECRET`; `YOUTUBE_CLIENT_ID`, `YOUTUBE_CLIENT_SECRET`, `YOUTUBE_REFRESH_TOKEN`, `YOUTUBE_CHANNEL_ID`; `CARTOONOS_MEDIA_BUCKET`, `CARTOONOS_MEDIA_S3_ENDPOINT`, `CARTOONOS_MEDIA_S3_REGION`, `CARTOONOS_MEDIA_S3_ACCESS_KEY_ID`, `CARTOONOS_MEDIA_S3_SECRET_ACCESS_KEY`; auth provider variables after provider selection; `CARTOONOS_PUBLIC_BASE_URL` and cost limits after enforcement exists. Model endpoints are selected from verified API documentation, never inferred from MCP IDs.

For future LLM retrieval/story runs, choose one provider and configure its server-side credential only when its adapter is implemented. No extra LLM vendor, vector service, CRM subscription, GPU rental, social MCP or multi-agent framework is required merely to start the pilot.

## Least access that supports each stage

1. Development audit: repo + read-only model/balance access; already available.
2. Evidence and references: source access and original binaries; keep licensed research material scoped.
3. Golden Shot: approved budget + generation account + private export storage. The founder must explicitly enable any purchase/subscription.
4. Analytics: owner OAuth with `yt-analytics.readonly`; Data API read-only scope for channel metadata as needed. Monetary reports require their supported monetary scope and entitlement. Confirm current report compatibility before queries.
5. Publishing: separate upload scope and release workflow; store audience setting, exact master and publication receipt. Request only when a reviewed pilot is ready.
6. Domain: deployment + DNS access to the chosen domain, private auth and SSL. Never publish the current unauthenticated prototype as an internal CRM.

OAuth tokens stay encrypted server-side. Bind each to organization/channel and record granted scopes, expiry, refresh success and revoke path. A valid-looking env value is not a connection test. No `NEXT_PUBLIC_*` secret variables.

## Setup procedure

From the repository root, run the doctor and validate commands in START_HERE, install the frozen JS dependencies, and launch `pnpm dev` on localhost. For the environment, copy `.env.example` to `.env` at the project root only if the file does not already exist, then run `uv sync --locked --group dev --extra analytics` from `backend`. Run checks before `uv run uvicorn cartoonos.api.main:app --host 127.0.0.1 --reload`.

The health endpoint currently proves process liveness only. It does not prove a live database, worker or provider. Database migrations, service readiness probes, worker bootstrap, authentication, durable storage and deployment remain tasks CO-006 onward. Do not add a blanket allow-all CORS setting to make the prototype connect.

For production: provision chosen DB/storage → migrations and isolation tests → worker/activity wiring → secret injection → owner auth → private preview → restore/security smoke tests → DNS and TLS → observe one controlled run → only then expand access. Configure backup, spend and failure alerts before claiming readiness.

Sources: [Higgsfield authentication](https://docs.higgsfield.ai/docs/authentication), [YouTube Analytics authorization](https://developers.google.com/youtube/analytics/guides/authorization).