buriedsignals/scoutpost-os/selfhost

Scoutpost self-hosted setup

Agent-agnostic skill. This file is the entry point whichever AI coding agent (Claude Code, Cursor, Codex, Windsurf, Gemini CLI, etc.) the user drops into the repo. It is intentionally tracked (lives under selfhost/, not .claude/) so every agent sees the same instructions.

This skill orchestrates the full deployment of Scoutpost on the user's own Supabase project. The canonical, step-by-step reference lives in selfhost/SETUP_AGENT.md — read that file in full before you start. It contains the exact commands for each step, including API-key collection, Supabase linking, Edge Function deployment, and the frontend build.

How agents activate this skill

• Claude Code: selfhost/SKILL.md is surfaced via the project's

CLAUDE.md ("Self-hosting setup lives in selfhost/"). When the user asks to set up / deploy / self-host, read this file first.

• Cursor / Windsurf: AGENTS.md at the repo root points at this file;

rules-file users can add a rule that says "for setup/deploy tasks, follow selfhost/SKILL.md".

• Generic (any MCP/CLI agent): the user can paste:

> Read selfhost/SKILL.md and follow it to set up Scoutpost.

Preconditions

No license key is required. The repository is public and self-hosting is free under the AGPL-3.0.

The user needs:

• Supabase account — managed cloud at supabase.com, or self-hosted via

Docker.

• API keys for OpenRouter, Firecrawl, Resend, Apify, and MapTiler (all

required).

• Signup controls — one admin email and the newsroom email domains allowed

to create accounts. Setup seeds a Supabase before-user-created Auth hook.

• Verified Resend sender domain — scouts can't send notifications without

it.

• Hosting target for the frontend — Render, Cloudflare Pages, Vercel, or

any static host that serves a SvelteKit static build.

• Node 22 LTS on the local machine running this skill — Node 25+ generates

lockfiles that break the Docker build.

Flow

1. Read `selfhost/SETUP_AGENT.md`. It is the source of truth.
2. Pre-flight checks — run the environment check from Step 1 of

SETUP_AGENT.md. Help the user install anything missing before continuing.

1. Clone / fork — the repo is public, clone via

gh repo fork buriedsignals/scoutpost-os --clone or plain git clone.

1. Collect setup values — prefer the /setup generator or

scoutpost-setup.json manifest so secrets stay out of chat. Explain what each service does. Do not skip MapTiler or the Resend domain verification step.

1. Provision Supabase — managed or self-hosted Docker. Run migrations

(supabase db push) and deploy all Edge Functions (supabase functions deploy; omitting a function name deploys all local functions).

1. Write `.env` — use .env.example as the template; fill in every

variable the user provided.

1. Build and deploy the frontend — `cd frontend && nvm use && npm ci &&

npm run build`, then push the static build to the chosen host.

1. Install the sync workflow — copy selfhost/sync-upstream.yml into

.github/workflows/ in the user's fork so upstream releases land as PRs. The workflow reports migrations and configured secrets; operators apply migrations and deploy Edge Functions after reviewing the PR.

1. Verify — hit the Supabase functions health endpoint, then the frontend

URL. Create the first user account.

Important behaviours

• Ask before spending money. Supabase Pro, Render paid tiers, and the

scout pipelines (Civic = 20 credits/run in hosted mode; real API cost self-hosted) all incur charges. Surface this before provisioning.

• Don't put secrets in chat. Use the generated manifest or local shell

prompts. Agents should read scoutpost-setup.json from disk and run selfhost/setup-from-manifest.sh.

• Don't assume defaults. Prompt the user for every decision and secret —

regions, tier selection, signup domains, sender address. No silent choices.

• One step at a time. Complete each step, summarise what was done, then

ask the user to confirm before the next step. The user must be able to audit the work as it happens.

• Use the existing automation when sensible. selfhost/setup.sh runs

the whole flow non-interactively if the user prefers a bash script over a chat-driven walkthrough. Offer it as an alternative at the start.

• Node 22 LTS is a hard requirement. If the user has a different major

version active, stop and walk them through nvm install 22 && nvm use 22 before the frontend build. Lockfile drift will otherwise break the Docker build on Render.

Files you will touch