simstudioai · brainx · Jul 21, 2026
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -165,12 +165,36 @@ After running this command, open [http://localhost:3000/](http://localhost:3000/
 git clone https://github.com/<your-username>/sim.git
 cd sim
 
+# Generate persistent secrets once (the file is ignored by Git)
+(
+  set -euC
+  if [ -e .env ]; then
+    echo 'Refusing to overwrite existing .env' >&2
+    exit 1
+  fi
+  umask 077
+  better_auth_secret=$(openssl rand -hex 32)
+  encryption_key=$(openssl rand -hex 32)
+  api_encryption_key=$(openssl rand -hex 32)
+  internal_api_secret=$(openssl rand -hex 32)
+  cat > .env << EOF
+BETTER_AUTH_SECRET=$better_auth_secret
+ENCRYPTION_KEY=$encryption_key
+API_ENCRYPTION_KEY=$api_encryption_key
+INTERNAL_API_SECRET=$internal_api_secret
+EOF
+)
+
 # Start Sim
 docker compose -f docker-compose.prod.yml up -d
 ```
 
 Access the application at [http://localhost:3000/](http://localhost:3000/)
 
+Back up this `.env` file separately in a secured secret store; do not bundle it with database
+backups. Do not regenerate the values when restarting an existing installation: changing encryption
+keys can make stored secrets unreadable, and changing `BETTER_AUTH_SECRET` invalidates sessions.
+
 #### Using Local Models
 
 To use local models with Sim:

diff --git a/README.md b/README.md
@@ -79,11 +79,36 @@ Docker must be installed and running. Use `-p, --port <port>` to run Sim on a di
 
 ```bash
 git clone https://github.com/simstudioai/sim.git && cd sim
+
+# Generate persistent secrets once (the file is ignored by Git)
+(
+  set -euC
+  if [ -e .env ]; then
+    echo 'Refusing to overwrite existing .env' >&2
+    exit 1
+  fi
+  umask 077
+  better_auth_secret=$(openssl rand -hex 32)
+  encryption_key=$(openssl rand -hex 32)
+  api_encryption_key=$(openssl rand -hex 32)
+  internal_api_secret=$(openssl rand -hex 32)
+  cat > .env << EOF
+BETTER_AUTH_SECRET=$better_auth_secret
+ENCRYPTION_KEY=$encryption_key
+API_ENCRYPTION_KEY=$api_encryption_key
+INTERNAL_API_SECRET=$internal_api_secret
+EOF
+)
+
 docker compose -f docker-compose.prod.yml up -d
 ```
 
 Open [http://localhost:3000](http://localhost:3000)
 
+Back up the generated `.env` file separately in a secured secret store; do not bundle it with
+database backups. Replacing its encryption keys can make stored secrets unreadable, while replacing
+`BETTER_AUTH_SECRET` invalidates existing sessions.
+
 Sim also supports local models via [Ollama](https://ollama.ai) and [vLLM](https://docs.vllm.ai/). See the [Docker self-hosting docs](https://docs.sim.ai/self-hosting/docker) for setup details.
 
 ### Manual Setup

diff --git a/apps/docs/content/docs/de/self-hosting/docker.mdx b/apps/docs/content/docs/de/self-hosting/docker.mdx
@@ -9,29 +9,57 @@ import { Callout } from 'fumadocs-ui/components/callout'
 ## Schnellstart
 
 ```bash
-# Clone and start
+# Clone the repository
 git clone https://github.com/simstudioai/sim.git && cd sim
+
+# Generate persistent secrets once (.env is ignored by Git)
+(
+  set -euC
+  if [ -e .env ]; then
+    echo 'Refusing to overwrite existing .env' >&2
+    exit 1
+  fi
+  umask 077
+  better_auth_secret=$(openssl rand -hex 32)
+  encryption_key=$(openssl rand -hex 32)
+  api_encryption_key=$(openssl rand -hex 32)
+  internal_api_secret=$(openssl rand -hex 32)
+  cat > .env << EOF
+BETTER_AUTH_SECRET=$better_auth_secret
+ENCRYPTION_KEY=$encryption_key
+API_ENCRYPTION_KEY=$api_encryption_key
+INTERNAL_API_SECRET=$internal_api_secret
+EOF
+)
+
+# Start Sim
 docker compose -f docker-compose.prod.yml up -d
 ```
 
 Öffnen Sie [http://localhost:3000](http://localhost:3000)
 
+<Callout type="warning">
+  Sichern Sie die erzeugte `.env` separat in einem geschützten Secret-Speicher und nicht zusammen
+  mit Datenbanksicherungen. Erzeugen Sie diese Werte bei einem Neustart nicht neu. Geänderte
+  Verschlüsselungsschlüssel können gespeicherte Secrets unlesbar machen; ein geändertes
+  `BETTER_AUTH_SECRET` macht bestehende Sitzungen ungültig.
+</Callout>
+
 ## Produktionseinrichtung
 
 ### 1. Umgebung konfigurieren
 
-```bash
-# Generate secrets
-cat > .env << EOF
-DATABASE_URL=postgresql://postgres:postgres@db:5432/simstudio
-BETTER_AUTH_SECRET=$(openssl rand -hex 32)
-ENCRYPTION_KEY=$(openssl rand -hex 32)
-INTERNAL_API_SECRET=$(openssl rand -hex 32)
+Behalten Sie die beim Schnellstart erzeugten Secrets und ergänzen Sie die öffentliche URL in
+derselben `.env`-Datei:
+
+```dotenv
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 BETTER_AUTH_URL=https://sim.yourdomain.com
-EOF
 ```
 
+Wenn Sie den Schnellstart übersprungen haben, führen Sie zuerst dessen Secret-Erzeugung aus.
+Ersetzen Sie niemals Verschlüsselungsschlüssel einer Installation, die bereits Daten enthält.
+
 ### 2. Dienste starten
 
 ```bash
@@ -125,6 +153,9 @@ docker compose -f docker-compose.ollama.yml exec ollama ollama pull llama3.2
 
 Wenn Ollama auf Ihrem Host-Rechner läuft (nicht in Docker):
 
+Führen Sie zuerst den Schnellstart aus, damit die persistente `.env` vorhanden ist. Verwenden Sie
+dann die passende Host-URL:
+
 ```bash
 # macOS/Windows
 OLLAMA_URL=http://host.docker.internal:11434 docker compose -f docker-compose.prod.yml up -d

diff --git a/apps/docs/content/docs/en/platform/self-hosting/docker.mdx b/apps/docs/content/docs/en/platform/self-hosting/docker.mdx
@@ -10,29 +10,56 @@ import { FAQ } from '@/components/ui/faq'
 ## Quick Start
 
 ```bash
-# Clone and start
+# Clone the repository
 git clone https://github.com/simstudioai/sim.git && cd sim
+
+# Generate persistent secrets once (the file is ignored by Git)
+(
+  set -euC
+  if [ -e .env ]; then
+    echo 'Refusing to overwrite existing .env' >&2
+    exit 1
+  fi
+  umask 077
+  better_auth_secret=$(openssl rand -hex 32)
+  encryption_key=$(openssl rand -hex 32)
+  api_encryption_key=$(openssl rand -hex 32)
+  internal_api_secret=$(openssl rand -hex 32)
+  cat > .env << EOF
+BETTER_AUTH_SECRET=$better_auth_secret
+ENCRYPTION_KEY=$encryption_key
+API_ENCRYPTION_KEY=$api_encryption_key
+INTERNAL_API_SECRET=$internal_api_secret
+EOF
+)
+
+# Start Sim
 docker compose -f docker-compose.prod.yml up -d
 ```
 
 Open [http://localhost:3000](http://localhost:3000)
 
+<Callout type="warning">
+  Back up the generated `.env` file separately in a secured secret store; do not bundle it with
+  database backups. Do not regenerate these values when restarting an existing installation.
+  Changing encryption keys can make stored secrets unreadable, while changing `BETTER_AUTH_SECRET`
+  invalidates existing sessions.
+</Callout>
+
 ## Production Setup
 
 ### 1. Configure Environment
 
-```bash
-# Generate secrets
-cat > .env << EOF
-DATABASE_URL=postgresql://postgres:postgres@db:5432/simstudio
-BETTER_AUTH_SECRET=$(openssl rand -hex 32)
-ENCRYPTION_KEY=$(openssl rand -hex 32)
-INTERNAL_API_SECRET=$(openssl rand -hex 32)
+Keep the secrets generated during Quick Start and add your public URL to the same `.env` file:
+
+```dotenv
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 BETTER_AUTH_URL=https://sim.yourdomain.com
-EOF
 ```
 
+If you skipped Quick Start, run its secret-generation step first. Never replace encryption keys for
+an installation that already has database data.
+
 ### 2. Start Services
 
 ```bash
@@ -121,6 +148,8 @@ docker compose -f docker-compose.ollama.yml exec ollama ollama pull llama3.2
 
 If Ollama runs on your host machine (not in Docker):
 
+Complete Quick Start first so the persistent `.env` exists, then use the appropriate host URL:
+
 ```bash
 # macOS/Windows
 OLLAMA_URL=http://host.docker.internal:11434 docker compose -f docker-compose.prod.yml up -d
@@ -158,4 +187,3 @@ docker compose -f docker-compose.prod.yml exec db pg_dump -U postgres simstudio
   { question: "How do I back up and restore the database?", answer: "Back up with: docker compose -f docker-compose.prod.yml exec db pg_dump -U postgres simstudio > backup.sql. Restore with: docker compose -f docker-compose.prod.yml exec -T db psql -U postgres simstudio < backup.sql. The database data is persisted in a Docker volume named postgres_data." },
   { question: "Can I customize the PostgreSQL credentials?", answer: "Yes. The docker-compose.prod.yml uses environment variable defaults: POSTGRES_USER (default: postgres), POSTGRES_PASSWORD (default: postgres), POSTGRES_DB (default: simstudio), and POSTGRES_PORT (default: 5432). Set these in your .env file to override them." },
 ]} />
-
diff --git a/apps/docs/content/docs/es/self-hosting/docker.mdx b/apps/docs/content/docs/es/self-hosting/docker.mdx
@@ -9,29 +9,57 @@ import { Callout } from 'fumadocs-ui/components/callout'
 ## Inicio rápido
 
 ```bash
-# Clone and start
+# Clone the repository
 git clone https://github.com/simstudioai/sim.git && cd sim
+
+# Generate persistent secrets once (.env is ignored by Git)
+(
+  set -euC
+  if [ -e .env ]; then
+    echo 'Refusing to overwrite existing .env' >&2
+    exit 1
+  fi
+  umask 077
+  better_auth_secret=$(openssl rand -hex 32)
+  encryption_key=$(openssl rand -hex 32)
+  api_encryption_key=$(openssl rand -hex 32)
+  internal_api_secret=$(openssl rand -hex 32)
+  cat > .env << EOF
+BETTER_AUTH_SECRET=$better_auth_secret
+ENCRYPTION_KEY=$encryption_key
+API_ENCRYPTION_KEY=$api_encryption_key
+INTERNAL_API_SECRET=$internal_api_secret
+EOF
+)
+
+# Start Sim
 docker compose -f docker-compose.prod.yml up -d
 ```
 
 Abre [http://localhost:3000](http://localhost:3000)
 
+<Callout type="warning">
+  Guarda el archivo `.env` generado por separado en un almacén seguro de secretos; no lo incluyas
+  con las copias de seguridad de la base de datos. No vuelvas a generar estos valores al reiniciar
+  una instalación existente. Cambiar las claves de cifrado puede hacer ilegibles los secretos
+  guardados, y cambiar `BETTER_AUTH_SECRET` invalida las sesiones existentes.
+</Callout>
+
 ## Configuración de producción
 
 ### 1. Configurar entorno
 
-```bash
-# Generate secrets
-cat > .env << EOF
-DATABASE_URL=postgresql://postgres:postgres@db:5432/simstudio
-BETTER_AUTH_SECRET=$(openssl rand -hex 32)
-ENCRYPTION_KEY=$(openssl rand -hex 32)
-INTERNAL_API_SECRET=$(openssl rand -hex 32)
+Conserva los secretos generados durante el Inicio rápido y añade la URL pública al mismo archivo
+`.env`:
+
+```dotenv
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 BETTER_AUTH_URL=https://sim.yourdomain.com
-EOF
 ```
 
+Si omitiste el Inicio rápido, ejecuta primero su paso de generación de secretos. No reemplaces las
+claves de cifrado de una instalación que ya tenga datos.
+
 ### 2. Iniciar servicios
 
 ```bash
@@ -125,6 +153,9 @@ docker compose -f docker-compose.ollama.yml exec ollama ollama pull llama3.2
 
 Si Ollama se ejecuta en tu máquina host (no en Docker):
 
+Completa primero el Inicio rápido para crear el `.env` persistente y después usa la URL de host
+adecuada:
+
 ```bash
 # macOS/Windows
 OLLAMA_URL=http://host.docker.internal:11434 docker compose -f docker-compose.prod.yml up -d

diff --git a/apps/docs/content/docs/fr/self-hosting/docker.mdx b/apps/docs/content/docs/fr/self-hosting/docker.mdx
@@ -9,29 +9,57 @@ import { Callout } from 'fumadocs-ui/components/callout'
 ## Démarrage rapide
 
 ```bash
-# Clone and start
+# Clone the repository
 git clone https://github.com/simstudioai/sim.git && cd sim
+
+# Generate persistent secrets once (.env is ignored by Git)
+(
+  set -euC
+  if [ -e .env ]; then
+    echo 'Refusing to overwrite existing .env' >&2
+    exit 1
+  fi
+  umask 077
+  better_auth_secret=$(openssl rand -hex 32)
+  encryption_key=$(openssl rand -hex 32)
+  api_encryption_key=$(openssl rand -hex 32)
+  internal_api_secret=$(openssl rand -hex 32)
+  cat > .env << EOF
+BETTER_AUTH_SECRET=$better_auth_secret
+ENCRYPTION_KEY=$encryption_key
+API_ENCRYPTION_KEY=$api_encryption_key
+INTERNAL_API_SECRET=$internal_api_secret
+EOF
+)
+
+# Start Sim
 docker compose -f docker-compose.prod.yml up -d
 ```
 
 Ouvrez [http://localhost:3000](http://localhost:3000)
 
+<Callout type="warning">
+  Sauvegardez le fichier `.env` généré séparément dans un gestionnaire de secrets sécurisé ; ne
+  l'incluez pas avec les sauvegardes de la base de données. Ne régénérez pas ces valeurs au
+  redémarrage d'une installation existante. Modifier les clés de chiffrement peut rendre les
+  secrets stockés illisibles, et modifier `BETTER_AUTH_SECRET` invalide les sessions existantes.
+</Callout>
+
 ## Configuration de production
 
 ### 1. Configurer l'environnement
 
-```bash
-# Generate secrets
-cat > .env << EOF
-DATABASE_URL=postgresql://postgres:postgres@db:5432/simstudio
-BETTER_AUTH_SECRET=$(openssl rand -hex 32)
-ENCRYPTION_KEY=$(openssl rand -hex 32)
-INTERNAL_API_SECRET=$(openssl rand -hex 32)
+Conservez les secrets générés lors du Démarrage rapide et ajoutez l'URL publique au même fichier
+`.env` :
+
+```dotenv
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 BETTER_AUTH_URL=https://sim.yourdomain.com
-EOF
 ```
 
+Si vous avez ignoré le Démarrage rapide, exécutez d'abord son étape de génération des secrets. Ne
+remplacez jamais les clés de chiffrement d'une installation qui contient déjà des données.
+
 ### 2. Démarrer les services
 
 ```bash
@@ -125,6 +153,9 @@ docker compose -f docker-compose.ollama.yml exec ollama ollama pull llama3.2
 
 Si Ollama s'exécute sur votre machine hôte (pas dans Docker) :
 
+Effectuez d'abord le Démarrage rapide afin de créer le fichier `.env` persistant, puis utilisez
+l'URL d'hôte appropriée :
+
 ```bash
 # macOS/Windows
 OLLAMA_URL=http://host.docker.internal:11434 docker compose -f docker-compose.prod.yml up -d