Skip to content
SoundverseSoundverse 2.0 — Engineering Docs

What works offline vs. what needs secrets

make up brings the whole backend up and healthy with zero external accounts. Every inter-service link inside the compose network is plaintext (h2c / gRPC, TLS off locally), so nothing internal needs a real credential. Only the features that reach outside the stack — an LLM proxy, the song-gen provider, blob storage, the identity provider — need a secret in your .env. This page is the map of which is which.

The two secrets that aren’t “external accounts”

Section titled “The two secrets that aren’t “external accounts””

Two secrets are required even for a fully offline run, but neither is an outside account — both are local plumbing:

  • GH_TOKEN — the one hard build-time requirement. Every backend image pulls private soundverse-* dependencies (proto, py, proto-go, proto-web) at build time via a BuildKit secret, so the image build fails without it. Scopes: repo + read:packages. gh auth token prints yours; make bootstrap writes it into .env. After the images are built it is never used again at runtime.
  • INTERNAL_RPC_SECRET — the shared internal gRPC bearer. make bootstrap generates a random value the first time it creates your .env. It must be identical across every service — if it drifts, workers can’t register and calls fail. See Configuring .env.

Works with no external secrets

Section titled “Works with no external secrets”

With just those two in place, the entire internal plane runs offline:

  • Inter-service gRPC/Connect calls across the compose network.
  • Postgres (via core-database, the only DB writer) and the schema-per-domain data model.
  • Redis — the queue-wake channel, cache, and rate-limit buckets.
  • The MCP tool registry and tool registration — a worker boots, registers its input/output schema, and upserts its pricing with no provider key.
  • Task-queue claiming, leases, heartbeats, and the reaper.
  • The schema-driven AI Tools panel — it populates as soon as a worker has registered, no frontend keys involved.

Needs a credential

Section titled “Needs a credential”

Each row below is a feature that reaches an external provider. Everything not in this table already works offline.

Feature Env var(s) it needs Behaviour without it
Blob uploads + HLS streams (tool outputs) make azurite-init (creates the blob containers) core-storage boots, but uploads and stream fetches 404 until the containers exist
Agent One LLM turns (core-tool-agent) LITELLM_API_KEY agent worker registers but can’t run a turn
Sansaarm song generation (core-tool-sansaarm) SANSAARM_API_BASE_URL, SANSAARM_API_KEY, SANSAARM_MODEL_V5 worker registers but can’t generate
Album art (core-tool-media) REPLICATE_API_TOKEN worker boots; returns the curated fallback cover instead of a generated image
Browser login + end-to-end chat (SaaS) AUTH_LOGTO_ID, AUTH_LOGTO_SECRET, AUTH_LOGTO_ISSUER, AUTH_LOGTO_RESOURCE (a real Logto OIDC app) SaaS UI loads but can’t authenticate, so no end-to-end chat
Subscription checkout / webhooks (core-billing) HYPERSWITCH_API_KEY, HYPERSWITCH_PROFILE_ID, HYPERSWITCH_WEBHOOK_SECRET billing boots, seeds plans, serves /plans + /entitlements; only checkout, webhooks, and the recurring loop need a real PSP

Blob uploads: run azurite-init once

Section titled “Blob uploads: run azurite-init once”

The azurite container (the local Azure Blob emulator) comes up with the stack via AZURE_CONNECTION_STRING, but starts with no containers. Run make azurite-init once after make up and before exercising any upload. Skip it and tool outputs — and the live HLS preview container — 404 on write. See Quick start with docker-compose.

Agent LLM turns

Section titled “Agent LLM turns”

The agent talks to the self-hosted LiteLLM proxy (LITELLM_BASE_URL has a working default; only LITELLM_API_KEY is blank in the sample env). The three tiers route via litellm prefix routing: AGENT_FLASH_MODEL, AGENT_STANDARD_MODEL, and AGENT_PRO_MODEL.

Browser login is Logto, not Zitadel

Section titled “Browser login is Logto, not Zitadel”

End-to-end chat from the browser needs a real Logto OIDC app — the gateway only accepts authenticated consumer calls. The frontend reads AUTH_LOGTO_ID, AUTH_LOGTO_SECRET, and AUTH_LOGTO_ISSUER, and the backend core-identity maps AUTH_LOGTO_ISSUER / AUTH_LOGTO_RESOURCE onto its IDP_ISSUER / IDP_AUDIENCE.

UI2.0 needs nothing at all

Section titled “UI2.0 needs nothing at all”

Fully standalone The UI2.0 in-browser music studio is completely self-contained and runs with no backend — it needs none of the secrets above. Run it on its own when you’re working on the studio UI in isolation. See Run the frontends.

Section titled “Related”