Run it yourself
No license key, no phone-home, no feature gate. Every environment variable is optional, and what you set is what runs.
There is no license key, no phone-home, and no feature gate. Self-hosting runs at the providers' own cost — the hosted version adds a margin on top of that, which is what pays for it to keep existing.
Your own keys on the hosted version
Not enabled in the alpha
Not enabled on the hosted version during the alpha. Self-hosting, above, works today. The steps below describe how it works once it is enabled.
All-or-nothing per report, deliberately: if any paid provider is still ours, the report is charged normally — otherwise we would be paying the largest line on the ledger for you. Your keys are encrypted before they are stored and are never shown back to you; the settings page can only ever display the last four characters.
What works with no keys at all
The reputation check runs entirely on public endpoints — Wikipedia and Wikidata, Google News, Reddit, Bluesky, the app stores, the podcast index, Trustpilot, autocomplete. The ads check falls back to deterministic transparency-center links. The SEO check falls back to a free intelligence pass over the site itself. You get a real, smaller report, and every check you have no key for is named as unavailable rather than quietly skipped.
Every environment variable
Every variable is optional. Set the ones you have; the readiness map decides what runs from what is present, and reports the rest by name.
# Every one of these is optional. What you set is what runs.
# The site capture — and with it logos, colors, typography, screenshots
FIRECRAWL_API_KEY=
# Search, SEO, reviews, backlinks, AI visibility
DATAFORSEO_LOGIN=
DATAFORSEO_PASSWORD=
# Social profiles and posts, and the ad-transparency archives
SCRAPECREATORS_API_KEY=
# Every model call, when no Gateway key is set
OPENAI_API_KEY=
# --- alternates, all off by default ---
SERPER_API_KEY= # takes over the search leg from DataForSEO
SERPAPI_API_KEY= # held, but nothing calls it yet
AI_GATEWAY_API_KEY= # one key for many models; every model call prefers it
APIFY_TOKEN= # an alternate route to Instagram and TikTok
YOUTUBE_API_KEY= # YouTube from Google, on a free quota
META_ADLIB_TOKEN= # real Facebook ad rows, free from Meta
BRANDFETCH_API_KEY= # a logo fallback
BRAVE_SEARCH_API_KEY= # search context, local lane only
GOOGLE_PLACES_API_KEY= # local lane only; the hosted report never calls it
# --- spend controls, off by default ---
# Hard daily ceiling on DataForSEO spend, in dollars, per process, fail-closed.
# Unset = no cap. Recommended for a hosted deployment: 5 — the one real
# runaway day on record ($27.15, 53.3% of the account) would have been cut
# off at ~18% of its burn. Generic form for any provider:
# BRAND_STUDIO_PROVIDER_DAILY_USD_CAP_<PROVIDER>=
BRAND_STUDIO_DATAFORSEO_DAILY_USD_CAP=
# Dev deployments only: let a FUNDED pull reserve even when its plan holds
# dollar-billed units with no measured price (the reservation otherwise
# refuses with reason "unpriced_plan_units" and stores nothing). The bypass
# is receipted on the pull row, never silent.
BRAND_STUDIO_ALLOW_UNPRICED_PULLS=Getting a key for each
Hosted, or your own
The hosted version charges more than a pull costs. That difference is margin, and it is what pays for the hosting, the queue, the storage and the work of keeping the collectors alive as the platforms change underneath them. Self-hosting has no such margin: you pay your providers directly, at their prices, and nothing routes through us.
Running it
git clone <this repository>
cd brand-studio-lightweight-system
npm install
cp .env.example .env # paste in whichever keys you have
npm test # everything runs offline, no key required
# one report, from one URL
node scripts/brand-studio-live-server.mjsWhere a model touches your report
Five bounded calls, one door, and the priced shortlist of models behind it. None of them can add a fact to your report.
For agents
Service-account API keys, the MCP endpoint and its tools, idempotent retries, and the contract-version promise — how a program calls this product, not a person.