# Self-Hosted Deployment Guide Minimal guide to get Mushi Mushi running on your own Supabase project. > **Fastest path:** from a clone of this repo, run > `npx mushi-mushi@latest selfhost up --project-ref ` — it wraps > every step below (link → db push → secrets → function deploys → bucket → > bootstrap) and ends with a health-check proof step. No Supabase CLI? > Pass `--print-commands` to get the exact commands to copy-paste. > Afterwards, `mushi selfhost doctor` verifies the deployment end to end. > The manual steps below remain the reference for what "up" does. ## Prerequisites - [Supabase CLI](https://supabase.com/docs/guides/cli) installed - A Supabase project (free tier works) - An [Anthropic API key](https://console.anthropic.com/) - (Optional) An [OpenAI API key](https://platform.openai.com/) for LLM failover ## 1. Clone and configure ```bash git clone https://github.com/kensaurus/mushi-mushi.git cd mushi-mushi/packages/server/supabase ``` Link to your Supabase project: ```bash npx supabase link --project-ref YOUR_PROJECT_REF ``` ## 2. Run database migrations ```bash npx supabase db push ``` This creates all tables, RLS policies, indexes, and RPCs. ## 3. Set secrets ```bash npx supabase secrets set ANTHROPIC_API_KEY=sk-ant-... # Optional: failover provider npx supabase secrets set OPENAI_API_KEY=sk-... # Required for report deep-links in Slack / Discord notifications. # Set this to the base URL of your deployed admin console (no trailing slash). # Example: https://your-domain.example.com/admin # On kensaur.us this is: https://kensaur.us/mushi-mushi/admin # When unset, notification buttons degrade gracefully (no URL, no crash). npx supabase secrets set ADMIN_BASE_URL=https://your-domain.example.com/admin ``` ## 4. Deploy Edge Functions Three functions are required for the core ingest + classification pipeline: ```bash npx supabase functions deploy api --no-verify-jwt npx supabase functions deploy fast-filter --no-verify-jwt npx supabase functions deploy classify-report --no-verify-jwt ``` Also deploy **`mcp`** if you use the hosted MCP transport: ```bash npx supabase functions deploy mcp --no-verify-jwt # Voice loop + cloud agents (2026-09-12): all authenticate inside the handler npx supabase functions deploy telegram-webhook --no-verify-jwt npx supabase functions deploy cursor-webhook --no-verify-jwt npx supabase functions deploy agent-status-poll --no-verify-jwt ``` Deploy every directory under `packages/server/supabase/functions/` except `_shared`, or mirror [`.github/workflows/deploy-edge-functions.yml`](.github/workflows/deploy-edge-functions.yml). Run `pnpm docs-stats` for the current function count. Optional functions: ```bash npx supabase functions deploy judge-batch --no-verify-jwt npx supabase functions deploy intelligence-report --no-verify-jwt npx supabase functions deploy generate-synthetic --no-verify-jwt ``` ### Closed-loop evolution functions (Phase 1–6) All six phases of the closed-loop pipeline have self-hosted parity. Deploy them with: ```bash # Phase 1 — Mistake clustering + lessons npx supabase functions deploy mistake-clusterer --no-verify-jwt npx supabase functions deploy mistake-summarizer --no-verify-jwt # Phase 2 — Release builder npx supabase functions deploy release-builder --no-verify-jwt # Phase 3 — PDCA autonomous iteration npx supabase functions deploy pdca-runner --no-verify-jwt # Phase 4 — Contract drift detection npx supabase functions deploy contract-graph-builder --no-verify-jwt npx supabase functions deploy drift-walker --no-verify-jwt # Phase 5 — A/B experiment analyzer npx supabase functions deploy experiment-analyzer --no-verify-jwt # Phase 6 — Anomaly detection npx supabase functions deploy anomaly-detector --no-verify-jwt ``` #### Voice intake, Telegram and cloud agents - `POST /v1/intake/voice` (in `api`) takes a project API key with the `voice:write` scope; enable `voice_intake_enabled` per project in the console first. Transcription uses the project's OpenAI key (`gpt-transcribe`, then `gpt-4o-mini-transcribe`); audio is deleted after transcription unless `voice_audio_retention_days` is set. - Telegram: create a bot with @BotFather, paste the token in the project's Voice intake settings (stored as a vault reference), call `POST /v1/admin/telegram/setup` (registers the webhook at `/functions/v1/telegram-webhook?project=` with a secret token), mint a bind code with `POST /v1/admin/telegram/bind-code`, then send `/start

` to the bot.
- Slack: re-install the app from `packages/plugin-slack-app/manifest.json` (new scopes `files:read`, `commands`, history events) after deploying `api`; Slack verifies the Events URL on save.
- Cursor Cloud: `autofix_agent = 'cursor_cloud'` or `mushi fix --agent cursor_cloud`; uses the v1 API with the project's Cursor key. Completion is polled by `agent-status-poll` (cron `5-55/5`); set `CURSOR_USE_V0_WEBHOOK=1` to use the v0 callback into `cursor-webhook` instead (secret derived from `MUSHI_INTERNAL_CALLER_SECRET`).
- GitHub cloud agent: `autofix_agent = 'github_cloud_agent'`; needs a user-to-server token (fine-grained PAT with "Agent tasks" read+write plus Contents and Pull requests, or a GitHub App user token) stored as `project_settings.github_user_token_ref` or `GITHUB_TOKEN`, and a Copilot plan with the coding-agent policy enabled. Installation tokens are rejected by GitHub.
- Web Push: set `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY`, `VAPID_SUBJECT` (mailto:) as edge secrets; the installed console PWA subscribes devices.

#### Required secrets for closed-loop functions

```bash
# Already required for classify-report:
npx supabase secrets set ANTHROPIC_API_KEY=sk-ant-...
npx supabase secrets set OPENAI_API_KEY=sk-...

# Required for mistake-clusterer + pdca-runner (OpenAI embeddings):
npx supabase secrets set OPENAI_API_KEY=sk-...
```

#### Recommended pg_cron schedules

Use `mushi.edge_function_post(fn_name, body)` — the same helper every
healthy cron job on the hosted project uses. **Do not** use
`current_setting('app.settings.supabase_url')` / `service_role_key`; those
GUCs return NULL on hosted Supabase and pg_cron will fail silently every
tick with `null value in column "url" of relation "http_request_queue"`.

Prerequisites (once per project):

```sql
-- Mirror the internal caller token + project URL into mushi_runtime_config
-- (the hosted project already has these; self-hosted operators set them once):
INSERT INTO public.mushi_runtime_config (key, value) VALUES
  ('supabase_url', 'https://YOUR_PROJECT_REF.supabase.co'),
  ('service_role_key', 'YOUR_INTERNAL_CALLER_SECRET'),
  -- Required by the pipeline-recovery cron (recover_stranded_pipeline):
  -- generate one secret (e.g. `openssl rand -hex 32`) and use the SAME value
  -- for this row and the MUSHI_INTERNAL_CALLER_SECRET function secret below.
  -- If this row is missing, recovery runs log status='skipped' in cron_runs
  -- and stranded reports are never retried.
  ('internal_caller_token', 'YOUR_INTERNAL_CALLER_SECRET')
ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, updated_at = now();
```

```bash
# The matching function secret (edge functions verify recovery calls with it):
npx supabase secrets set MUSHI_INTERNAL_CALLER_SECRET=YOUR_INTERNAL_CALLER_SECRET
```

Verify recovery is healthy after setup (should show `success`/`degraded`, not
`skipped`, and `responses_failed: 0` once reconciled):

```sql
SELECT status, metadata FROM cron_runs
 WHERE job_name = 'pipeline-recovery'
 ORDER BY finished_at DESC LIMIT 3;
```

Schedules:

```sql
-- Mistake clusterer: every 6 hours
SELECT cron.schedule(
  'mushi-mistake-clusterer',
  '0 */6 * * *',
  $$ SELECT mushi.edge_function_post('mistake-clusterer', '{}'::jsonb); $$
);

-- Drift walker: daily at 03:00 UTC (per project — adapt body)
SELECT cron.schedule(
  'mushi-drift-walker',
  '0 3 * * *',
  $$ SELECT mushi.edge_function_post('drift-walker', '{"project_id":"YOUR_PROJECT_ID"}'::jsonb); $$
);

-- Anomaly detector: hourly
SELECT cron.schedule(
  'mushi-anomaly-detector',
  '0 * * * *',
  $$ SELECT mushi.edge_function_post('anomaly-detector', '{"project_id":"YOUR_PROJECT_ID"}'::jsonb); $$
);
```

> **Re-deploys overwrite source.** Supabase keeps the file bundle as the source
> of truth; if a deploy uploads a stale `index.ts` (e.g. you forgot to save before
> deploying) the function will silently miss new routes. After deploying, smoke
> the endpoints with `curl` to catch this. We hit it during initial admin route
> rollout — see commit history for the affected revision.

## 5. Create a Supabase storage bucket

In your Supabase dashboard, create a storage bucket named `screenshots` with public access.

## 6. Verify the deployment

```bash
# API liveness (process up — does not prove DB)
curl https://YOUR_PROJECT_REF.supabase.co/functions/v1/api/health
# Should return: {"status":"ok","version":"1.0.0",…}

# API readiness (fails when Postgres is unreachable)
curl https://YOUR_PROJECT_REF.supabase.co/functions/v1/api/health/ready

# Standalone healthz edge function (no JWT; cheap DB probe)
curl https://YOUR_PROJECT_REF.supabase.co/functions/v1/healthz
# Should return: {"status":"ok","db":"ok","version":"…"}  (or status "degraded" if DB probe fails)
```

## 7. Connect the SDK

```tsx
import { MushiProvider } from '@mushi-mushi/react'

function App() {
  return (
    
      
    
  )
}
```

To get `projectId` and `apiKey`, sign in to the admin console or create them via SQL:

```sql
-- Create a project
INSERT INTO projects (name, slug)
VALUES ('My App', 'my-app')
RETURNING id;

-- Create an API key (save the raw key — it's shown only once)
-- Use the CLI: mushi login --api-key  --endpoint 
```

## 8. Run the Admin Console (optional)

```bash
cd apps/admin
cp .env.example .env
# Set VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY
pnpm install && pnpm dev
```

## Pipeline Flow

```
SDK → api (ingestion) → fast-filter (Haiku Stage 1)
                            ↓ (low confidence)
                       classify-report (Sonnet Stage 2)
```

## Scheduling judge-batch

The `judge-batch` function runs nightly LLM-as-Judge quality evaluation. Schedule it with `pg_cron`, using the same `mushi.edge_function_post` helper as the other schedules above (requires the [prerequisites](#recommended-pg_cron-schedules) — do **not** use `current_setting('app.settings.…')`, which returns NULL on hosted Supabase and fails silently):

```sql
SELECT cron.schedule(
  'mushi-judge-batch',
  '0 3 * * *',
  $$ SELECT mushi.edge_function_post('judge-batch', '{}'::jsonb); $$
);
```

Or use an external cron service (GitHub Actions, cron-job.org, etc.) that POSTs to the function URL.

## Security Notes

**Edge function auth:** The `api` function authenticates via API key (hashed lookup in `project_api_keys`) and JWT (Supabase auth). Internal functions (`fast-filter`, `classify-report`, `judge-batch`, `intelligence-report`, `generate-synthetic`) authenticate via `SUPABASE_SERVICE_ROLE_KEY` comparison. Only the `api` function should be exposed to the internet. The others should be invoked server-side (by `api` or by `pg_cron`).

**Screenshot capture limitations:** The SDK captures screenshots using canvas/SVG `foreignObject` serialization. This approach does not work with cross-origin iframes, tainted `