Verify your install

Run these checks after installation, an upgrade, or a restore. Use a test workspace and the providers you configured. Also test optional features you enabled, such as SSO, SCIM, data drains, and remote sandboxes.

Run doctor

For Compose or a source checkout, run from the directory holding your env files:

bunx sim-setup doctor

Doctor reports these groups:

Doctor reads env files, not live container configuration. Production Compose derives DATABASE_URL and Redis settings in the service definition, so those probes can be skipped when the keys are absent from .env. A standalone published package has no migration journal: it can report applied migrations, but cannot establish that they match a current checkout. Read the skipped findings and continue with the checks below.

--json prints structured findings; the command exits 1 when a check fails. --fix writes env-file repairs and reruns the checks. Review those changes and recreate the affected services to apply them; retain existing encryption secrets on upgrades and restores.

Doctor is not a Helm runtime diagnostic. For Kubernetes, use the infrastructure commands below. See Setup commands for the supported layouts and commands.

Core checks

Two windows verify collaboration between clients. To establish cross-replica operation, also confirm their socket connections reach different realtime pods. A load balancer can send both windows to one process. Multi-replica operation requires REDIS_URL on the app and realtime services.

Cloud uploads use multipart above 50 MiB; local uploads use it above 8 MiB. Local parts pass through Sim, while cloud parts use signed provider URLs. See Object storage.

Feature checks

Run the checks for each feature you intend to use:

Knowledge bases can use OpenAI, Azure OpenAI, OpenRouter, or Gemini embeddings, or an Ollama model selected by KB_EMBEDDING_MODEL=ollama/<model> with OLLAMA_URL. See Environment variables.

Infrastructure checks

For the Helm example release sim in namespace simstudio:

kubectl get pods -n simstudio
kubectl logs -n simstudio deploy/sim-app -c migrations --tail=50
curl -fsS https://sim.yourdomain.com/api/health
kubectl get cronjobs -n simstudio

The migrations init container must complete before the app starts. Inspect failed CronJob pods and their logs; the presence of a schedule alone does not prove the endpoint call succeeded.

To check whether Redis is configured without printing the connection string:

kubectl exec -n simstudio deploy/sim-app -- sh -c 'test -n "$REDIS_URL"'

A zero exit status only confirms a non-empty variable. It does not prove Redis answers or that cross-pod events propagate; use the collaboration check above.

For Compose:

docker compose -f docker-compose.prod.yml ps -a
docker compose -f docker-compose.prod.yml logs migrations
docker compose -f docker-compose.prod.yml logs cron
curl -fsS http://localhost:3000/api/health

Expect simstudio, realtime, db, redis, and cron to be running, with migrations completed successfully. Without CRON_SECRET, the cron service exits instead of running schedules.

Read failures

Set LOG_LEVEL=INFO and restart/recreate the app to see email no-op logs. Log-level values are uppercase; the production default is ERROR, which hides those INFO messages. Message bodies are not logged and cannot be recovered from that no-op entry.

After an upgrade

Repeat app sign-in, realtime collaboration, workflow execution, file upload/download, and scheduled-run checks at minimum. Also test each optional feature affected by the release.

After a restore

Run all applicable checks. Run a workflow using a previously saved provider key and an OAuth-backed integration to confirm the restored database and ENCRYPTION_KEY still match. An app can load and sign in while stored credentials remain unreadable.

Related docs

• Background jobs
• Networking
• Troubleshooting