Skip to content

Testing on staging (QA & devs)

Share this page. It's everything you need to start exercising Sudo on staging — no VPS or GitHub access required.

What staging is

A complete, separate copy of Sudo that auto-deploys every time a dev pushes to main. It has its own database, accounts, WhatsApp number, and voice server — nothing you do here touches production or real users. Break it freely.

Surface URL
Web app (chat, integrations) https://staging.sudohomes.com
Admin (LLM settings) https://staging.sudohomes.com/admin/settings
Marketing homepage https://staging.heysudo.xyz
Database UI (Supabase Studio) https://db-staging.sudohomes.com (ask a dev for the basic-auth login)

Staging only

Never sign in to or test against sudohomes.com (production, real users) when you mean to test a candidate build. Staging is staging.sudohomes.com.

1. Get an account

Sign in at https://staging.sudohomes.com with Google (the only sign-in method). Your staging account is brand-new and unrelated to any prod account, even with the same email. To get admin access (the /admin/* pages), ask a dev to add your email to the staging ADMIN_EMAILS.

2. Test the web surfaces

  • Chat — /chat. Send a message; the assistant should stream a reply token-by-token. Open a second tab — replies should appear in both.
  • Integrations — /integrations. Connect Home Assistant, set a voice, link WhatsApp.
  • Admin settings — /admin/settings. The LLM provider/model/key is global. Changing it restarts every running assistant, so confirm chat still answers after a save.

3. Test WhatsApp (Twilio sandbox)

Staging uses Twilio's sandbox number +1 (415) 523-8886, not the real Business number.

  1. From your phone, send join <sandbox-code> to that number on WhatsApp (a dev can give you the current join code from the Twilio console).
  2. On staging /integrations, add your phone number as a family member.
  3. Message the sandbox number — the assistant should reply.

4. Test voice (a Pi pointed at staging)

A Pi follows whichever environment it was paired against. To put a QA Pi on staging: on the Pi, set SUDO_API_URL and PUBLIC_APP_URL to https://staging.sudohomes.com in /opt/sudo/.env, systemctl restart sudo-edge, then pair it while signed into staging.sudohomes.com. After that it's pinned to staging and survives later .env drift.

5. Know when your build is live (devs)

A push to main triggers the staging deploy automatically — but only when it touches paths the workflow watches (cloud/**, homepage/**, compose.prod.yaml, caddy/**, deploy/**, supabase/migrations/**). A docs-only change outside cloud/wiki/ won't deploy. Watch a run finish before testing:

gh run list --workflow=deploy-staging.yml      # latest runs + status
gh run watch <run-id>                          # live, until it completes

A deploy takes a few minutes (it rebuilds images and recreates assistants). If your change isn't showing up, the run is probably still in flight or it failed — check the run first.

This wiki deploys with the app

These pages live under cloud/wiki/, so editing them ships to staging.sudohomes.com/docs/ on the same push-to-main deploy. Repo-root docs/ is not served here.

6. Report a bug

Include: the surface (chat / voice / WhatsApp / admin), the URL or action, what you expected vs. saw, and the time (so devs can find it in logs). A dev can then pull the matching logs from Grafana (grafana.sudohomes.com) — staging logs land there too, by container name.