Configuration
Every setting for a Compose install lives in one file: infra/compose/.env. The installer writes it on the first run with generated secrets and a few defaults. This page lists every setting you can put there, grouped by topic, with its default and what it does.
If you run Casama with Helm or on a platform like Render or Railway, the same names apply as environment variables on the API, worker and supervisor. See Database and auth for the ones Compose sets for you.
Change a setting
Edit
infra/compose/.env. Use oneNAME=valueper line. An empty value counts as unset.Apply it:
shcasama selfhost upOr, without the CLI:
shdocker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env up -d
Compose recreates every service whose settings changed. All Casama services read their settings only at start, so every change needs this step. docker compose restart is not enough: it restarts containers with their old settings.
Tip: Optional profiles
casama selfhost upnames no Compose profile exceptlink, which it adds while remote access is on. If you changed a setting for the web app, monitoring, search, page PDFs or backups, add the profile:docker compose ... --profile monitoring up -d. Docker Compose also readsCOMPOSE_PROFILESfrom the env file, soCOMPOSE_PROFILES=monitoring,webin.envkeeps them on for every command. Re-running./install.shadds thebackupprofile by itself once you installed with--backups.
Some settings are read by the server but not passed through by the bundled compose file. They're listed under Advanced settings, with how to add them.
Core and URLs
| Name | Default | What it does |
|---|---|---|
CASAMA_SITE | Set by the installer | What Caddy serves: a domain (casama.example.com, automatic HTTPS) or :80 (plain HTTP, for --local or behind another proxy). |
CASAMA_PUBLIC_URL | Set by the installer | The public address, for example https://casama.example.com. Used as the API, app and Supabase address and for Auth redirects. |
HTTP_PORT | 80 | Host port Caddy listens on for HTTP. |
HTTPS_PORT | 443 | Host port Caddy listens on for HTTPS. |
CASAMA_PAGES_SITE | :8790 | What Caddy serves Pages on: a domain of its own (pages.example.com, automatic HTTPS) or a port. |
CASAMA_PAGES_URL | http://localhost:8790 | The public address of Pages, used in links to bots' pages. Set it to match CASAMA_PAGES_SITE. |
PAGES_PORT | 8790 | Host port Caddy publishes for Pages. |
CORS_ORIGINS | (empty) | Extra comma-separated web origins allowed to call the API from a browser. The public address is always allowed. |
RATE_LIMIT_PER_MINUTE | 120 | Requests per minute on the API and webhooks, per signed-in user or else per IP address. Casama Link endpoints get ten times as much. |
UPDATE_CHECK_URL | (empty: no update checks) | Where the admin console checks for new releases, in the shape of GitHub's latest-release API. |
CASAMA_REGISTRY | casama (build locally) | Where the Casama images come from. ./install.sh --pull sets ghcr.io/stackwares/casama, and re-runs then pull instead of build. |
CASAMA_VERSION | local | The tag of the Casama images Compose builds or pulls. --pull [tag] sets it (default latest). |
CASAMA_SERVER_IMAGE | (empty: registry and tag above) | Runs the API and worker on one exact image, such as your own build of apps/server/Dockerfile. Upgrades leave it alone; empty it to go back. |
HTTP_BIND | 0.0.0.0 | The address Caddy's HTTP, HTTPS and Pages ports listen on. --behind-proxy and --local set 127.0.0.1. |
TRUSTED_CLIENT_IP_HEADER | (empty: X-Forwarded-For) | A header your edge sets with the caller's address, for rate limits on signed-out requests. Behind Cloudflare, cf-connecting-ip. |
AUTH_RATE_LIMIT_HEADER | (empty: Auth's default) | The same for Supabase Auth's per-caller sign-in limits. Behind Cloudflare, cf-connecting-ip. |
CASAMA_CONTAINER_PREFIX | casama | Prefix of the fixed container names and of bot computers' containers, networks and volumes. Change it to run two stacks on one machine. |
PAIR_LINK_URL | https://casama.ai/pair | The page a sign-in QR code opens, which hands the code to the app. The code rides after #, so the page never receives it. |
Pages on their own domain. Bots' web pages are served from a separate origin so a page's scripts never share an origin with Casama. On a public server, give them their own name:
CASAMA_PAGES_SITE=pages.casama.example.com
CASAMA_PAGES_URL=https://pages.casama.example.comPoint the name's DNS at the server; Caddy gets its certificate automatically.
Change the address after installing. Re-running the installer doesn't change the address. Edit these together, then run casama selfhost up:
CASAMA_SITE=casama.example.com
CASAMA_PUBLIC_URL=https://casama.example.com
TURN_PUBLIC_HOST=casama.example.com
SIGNUP_HOOK_URI=https://casama.example.com/hooks/auth/before-user-createdBehind another proxy
If a load balancer or another reverse proxy terminates TLS:
- Set
CASAMA_SITE=:80so Caddy serves plain HTTP../install.sh --behind-proxy --domain <name>does this. - Keep
CASAMA_PUBLIC_URLon the publichttps://address. - Route your proxy to Caddy's HTTP port (
HTTP_PORT), including WebSocket upgrades. - Set
HTTP_BIND=127.0.0.1(the installer does this with--behind-proxy). Docker-published ports skip the host firewall, so0.0.0.0would serve plain HTTP to anyone who can reach the server's IP. - Keep port 3478 (UDP and TCP) reachable directly for live view, and set
TURN_PUBLIC_HOST(--turn-host) to a name that points at the server with DNS only, not through the HTTP proxy. Media stays inside coturn, so the relay range 49160–49260 does not need to be open. - If the proxy is a tunnel on the same machine (Cloudflare Tunnel, for example), every request reaches Caddy from the tunnel's own address. Set
TRUSTED_CLIENT_IP_HEADERto the header that carries the real address (cf-connecting-ipfor Cloudflare), or all signed-out callers share one rate limit.
Generated secrets
The installer generates these on the first run. Don't edit them on a running server unless the table says it's safe: several are baked into the database or into each other.
| Name | What it is | Safe to change? |
|---|---|---|
POSTGRES_PASSWORD | Password for Postgres and the Supabase service roles | No. Postgres keeps the password it was first started with. |
WORKER_DB_PASSWORD | Password for casama_worker, the worker's least-privilege database role | Yes. The migrate service sets it again at every start. |
AUTH_HOOK_SECRET | Shared secret for the sign-up hook (v1,whsec_…), on Auth and the API | Yes, if you change it in both places and restart Auth and the API. |
JWT_SECRET | Signs Supabase tokens | No. ANON_KEY and SERVICE_ROLE_KEY are signed with it. |
ANON_KEY | Supabase anon key (a JWT) | No |
SERVICE_ROLE_KEY | Supabase service role key (a JWT) | No |
SECRET_KEY_BASE | Supabase Realtime's secret | No |
REALTIME_ENC_KEY | Supabase Realtime's encryption key | No |
SAML_PRIVATE_KEY | Supabase Auth's SAML signing key (RSA, PKCS#1, base64 DER) | No |
SUPERVISOR_TOKEN | The API and worker's token for the supervisor (16+ characters) | Yes, with a full casama selfhost up |
COMPUTER_TOKEN_SECRET | Derives each computer's own tokens | No. Existing computers would stop answering. |
EGRESS_CONTROL_TOKEN | The supervisor's token for the egress proxy's control API | Yes, with a full casama selfhost up |
INTERNAL_TOKEN | Shared secret for the API's internal endpoints (32+ characters) | Yes, with a full casama selfhost up |
TURN_SECRET | coturn's shared secret for short-lived live view credentials (16+ characters) | Yes, with a full casama selfhost up |
SEARXNG_SECRET | SearXNG's own secret (search profile) | Yes, with a full casama selfhost up |
METRICS_TOKEN | Bearer token for /metrics (16+ characters) | Yes. Prometheus picks it up when it restarts. |
GRAFANA_ADMIN_PASSWORD | Grafana's admin password (monitoring profile) | Only before Grafana's first start; afterwards change it in Grafana. |
The installer also generates CONTENT_ENCRYPTION_KEY unless you use AWS KMS. See Encryption keys: it can't be changed like the others.
Database and auth
Compose wires these for the API and worker from the generated secrets. Set them yourself only on Helm, a platform like Render, or a custom setup.
| Name | Default | What it does |
|---|---|---|
MODE | api | api or worker. The API and worker are the same image. |
PORT | 8787 | The API's HTTP port. |
NODE_ENV | development | Set production in production (Compose does). |
DATABASE_URL | Required | Postgres URL with full access, for the API. |
WORKER_DATABASE_URL | Falls back to DATABASE_URL | The worker's least-privilege URL (casama_worker). Compose builds it from WORKER_DB_PASSWORD. |
SUPABASE_URL | Required | Supabase's public address. Compose uses CASAMA_PUBLIC_URL, since Caddy routes /auth/v1 and friends. |
SUPABASE_ANON_KEY | Required | Supabase anon key. The apps get it from the server. |
SUPABASE_JWT_SECRET | (empty: verify with JWKS) | Supabase's HS256 secret. When unset, tokens are checked against the project's JWKS. |
SUPABASE_SERVICE_ROLE_KEY | (empty) | Needed for SAML SSO administration and for sign-in codes (scan to sign in). |
SUPABASE_INTERNAL_URL | SUPABASE_URL | How the server reaches Supabase itself. Compose uses http://kong:8000, since the public address may not answer from inside the stack. |
PUBLIC_APP_URL | http://localhost:3000 | The app's public address. Always allowed by CORS. |
PUBLIC_API_URL | The request's origin | The API's public address, used in OAuth redirects, phone call webhooks and live view. |
PAGES_URL | http://localhost:8790 | Public address of Pages. Compose sets it from CASAMA_PAGES_URL. |
PAGES_PORT | (unset: Pages not served) | Port the API process serves Pages on. Compose uses 8790 inside the stack. |
API_INTERNAL_URL | http://127.0.0.1:$PORT | How the worker reaches the API's internal endpoints. |
INTERNAL_TOKEN | Derived from DATABASE_URL | Shared secret for internal endpoints. Always set a random value; the server warns in production without one. |
SUPERVISOR_URL | (unset: no computers) | The sandbox supervisor's address. Compose uses http://casama-supervisor:8788. |
SUPERVISOR_TOKEN | (unset) | Token for the supervisor. |
Page PDFs
Export PDF on a page prints it with headless Chromium. Chromium can't keep its own sandbox inside a normal container, so it runs in a container of its own (Gotenberg, about 500 MB) that holds no secrets and sits on a private network with only the API on it: no internet, no database. Pages are printed from what the API sends; outside URLs and other files are blocked.
- Add
pdftoCOMPOSE_PROFILESininfra/compose/.env(or pass--profile pdf). - Set
PDF_RENDERER_URL=http://pdf:3000in the same file. - Run
docker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env up -d.
| Name | Default | What it does |
|---|---|---|
PDF_RENDERER_URL | (empty: PDF export off) | The PDF sidecar's address. Compose: http://pdf:3000. |
On Helm, run gotenberg/gotenberg:8.39.0-chromium as its own Deployment with a NetworkPolicy that only lets the API in and nothing out, and set PDF_RENDERER_URL with extraEnv.
Invite links
Invite links are <PUBLIC_APP_URL>/join/<token>. With the web app running, it shows the invite; without it, Caddy sends /join/* to a small page from the API with Open in Casama. To have links open the installed apps directly, publish the app-link files:
| Name | Default | What it does |
|---|---|---|
APPLE_APP_IDS | (empty: no file) | iOS app ids (TEAMID.ai.casama.app, comma-separated) for /.well-known/apple-app-site-association. |
ANDROID_APP_PACKAGE | ai.casama.app | Android package for /.well-known/assetlinks.json. |
ANDROID_CERT_SHA256 | (empty: no file) | SHA-256 fingerprints of the Android signing certificates, comma-separated. |
APP_STORE_URL | (empty) | App Store page linked from the invite page. |
PLAY_STORE_URL | (empty) | Google Play page linked from the invite page. |
The apps only claim links for a domain built into them, so on your own domain links open the invite page, whose Open in Casama button opens the app and points it at your server.
Email
Supabase Auth sends sign-in links, confirmations and password resets through SMTP. Casama sends invites through the same SMTP server, or through Resend when RESEND_API_KEY is set. Email is optional: without it, people sign in with a password and invites return a code to share.
| Name | Default | What it does |
|---|---|---|
SMTP_HOST | (empty: Auth sends no email) | Your SMTP server. |
SMTP_PORT | 587 | SMTP port. 465 uses TLS from the start; other ports need STARTTLS. |
SMTP_USER | (empty) | SMTP user name. |
SMTP_PASS | (empty) | SMTP password. |
SMTP_ADMIN_EMAIL | (empty) | The address Auth emails come from. |
EMAIL_AUTOCONFIRM | true | Confirm new accounts without an email. Set false once SMTP works. |
RESEND_API_KEY | (empty) | Resend key for invite emails, used instead of SMTP. With neither, an invite returns a code to share. |
EMAIL_FROM | Casama <no-reply@localhost> | Sender for Casama's own emails. |
AUTH_SITE_URL | CASAMA_PUBLIC_URL | Where Auth's email links land when the app didn't ask for a place. Set it to your web app's address. |
EMAIL_TEMPLATE_* | Casama's branded templates | URLs of Auth's email templates (_MAGIC_LINK, _CONFIRMATION, _INVITE, _RECOVERY, _EMAIL_CHANGE, _REAUTHENTICATION). Override one to use your own. |
Links in Auth's emails go to <CASAMA_PUBLIC_URL>/auth/v1/verify, which Caddy sends to Auth.
To turn on email confirmation and sign-in links:
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=casama@example.com
SMTP_PASS=your-smtp-password
SMTP_ADMIN_EMAIL=casama@example.com
EMAIL_AUTOCONFIRM=falseSign-ups and allowlists
| Name | Default | What it does |
|---|---|---|
INSTANCE_ADMIN_EMAILS | (empty: the first account) | Comma-separated emails of instance owners, who get the admin console. |
DISABLE_SIGNUP | false | true turns off new sign-ups in Supabase Auth. |
SIGNUP_ALLOWED_EMAILS | (empty: anyone) | Only these emails or domains can sign up, comma-separated: ana@example.com,@example.org (example.org also works for a domain). |
SIGNUP_HOOK_ENABLED | false | true makes Supabase Auth call Casama's sign-up hook. Needed for the allowlist. |
AUTH_HOOK_SECRET | (empty) | The hook's signing secret, v1,whsec_<base64>. Shared by Auth and the API. |
SIGNUP_HOOK_URI | Set by the installer | Where Auth calls the hook: https://<domain>/hooks/auth/before-user-created. Empty for --local. |
ADDITIONAL_REDIRECT_URLS | casama://app/login-callback,http://127.0.0.1:*/auth/callback | Redirect URLs Supabase Auth accepts after sign-in, comma-separated. Keep the default for the apps: iPhone, Mac and Android come back on casama://, Windows and Linux on a listener on 127.0.0.1. |
SAML_ENABLED | true | SAML SSO in Supabase Auth. Workspaces register their identity provider through the API (needs an enterprise license). |
ABUSE_CONTROLS | auto (off when self-hosted) | auto, on or off. Sign-up proofs, verified email before computers start, and suspension on egress abuse. Meant for Casama Cloud. |
EGRESS_ABUSE | off | on makes the egress proxy refuse mail and crypto-mining traffic from computers and report it. |
To limit sign-ups to your team (needs a --domain install, because Supabase Auth only calls https hooks):
Generate a secret:
shecho "v1,whsec_$(openssl rand -base64 32)"Add to
infra/compose/.env:shSIGNUP_ALLOWED_EMAILS=@example.com,ana@example.org SIGNUP_HOOK_ENABLED=true AUTH_HOOK_SECRET=v1,whsec_...Run
casama selfhost up.
The allowlist applies to every sign-in method, Google and Apple included. Others see "limited to approved email addresses". An allowlist without a hook secret refuses every sign-up rather than allowing everyone.
Warning
SIGNUP_HOOK_URImust be empty or anhttps://address. A plainhttp://address stops Supabase Auth from starting, even with the hook turned off.
Apple and Google sign-in
The sign-in screen offers Continue with Apple and Continue with Google. A new server has both turned off, so people sign in with email until you set these. They are the accounts people use to enter Casama. A Google client for Gmail, Calendar and Drive is a different setup, under Integrations below.
| Name | Default | What it does |
|---|---|---|
APPLE_AUTH_ENABLED | false | true turns on Continue with Apple. |
APPLE_AUTH_CLIENT_IDS | (empty) | Comma-separated. The Services ID first, then the app id ai.casama.app. The first is the browser flow. The app id is the system sheet on iPhone and Mac. |
APPLE_AUTH_SECRET | (empty) | Apple's client secret, a signed token. It expires within six months. Make a new one from the same key before it does, or browser sign-in starts failing. |
GOOGLE_AUTH_ENABLED | false | true turns on Continue with Google. |
GOOGLE_AUTH_CLIENT_ID | (empty) | The web client id from Google Cloud. To let your own build of the app use Google's sign-in sheet on iPhone and Mac, add its iOS client id after a comma. |
GOOGLE_AUTH_SECRET | (empty) | That client's secret. |
Apple and Google both send people back to https://<your domain>/auth/v1/callback. Register that exact address. On Apple it is the return URL of the Services ID. On Google it is an authorized redirect URI of the web client. If Apple and Google reach Auth under another name than CASAMA_PUBLIC_URL, set that full address in AUTH_CALLBACK_URL.
- In the Apple Developer account, turn on Sign in with Apple for the app id
ai.casama.app. Create a Services ID and a key. Put the Services ID first inAPPLE_AUTH_CLIENT_IDS, thenai.casama.app. - In Google Cloud, create a web OAuth client (not an iOS or Android client) and copy its id and secret.
- Add the values to
infra/compose/.envand runcasama selfhost up.
Passkeys
People can sign in with a passkey (Face ID, a fingerprint or a screen lock) once they add one in Settings → Passkeys. On your own server this works in the browser, under your domain. The App Store and Google Play apps are tied to casama.ai, so they hide passkeys when connected to another server.
| Name | Default | What it does |
|---|---|---|
PASSKEYS_ENABLED | false | true turns on passkeys. |
PASSKEY_RP_ID | (empty) | Your domain without https://, for example casama.example.com. Required when on. |
PASSKEY_RP_ORIGINS | CASAMA_PUBLIC_URL | Comma-separated addresses the web app is served from, if more than the public address. |
A passkey belongs to its domain. Changing PASSKEY_RP_ID later means everyone adds theirs again.
iPhone and Mac use Apple's system sheet, so they need ai.casama.app in the client id list. Android, Windows, Linux and the web open the browser, which is what the secret is for. Keep casama://app/login-callback (Android) and http://127.0.0.1:*/auth/callback (Windows and Linux) in ADDITIONAL_REDIRECT_URLS. If the web app is served from another address, add that address too.
Models and AI Gateway
People add their own model keys in the app (Settings → Model keys) or with casama credential add. Any OpenAI-compatible endpoint works, including a local Ollama. These settings change server-wide defaults.
| Name | Default | What it does |
|---|---|---|
DEFAULT_MODEL_OPENROUTER | deepseek/deepseek-v4.1-flash-1017 | Default model for new bots on OpenRouter. |
DEFAULT_MODEL_OPENAI | gpt-6-luna | Default model for new bots on OpenAI. |
DEFAULT_REASONING_EFFORT | medium | none, low, medium, high, xhigh or max. |
LAZY_TOOLS_THRESHOLD | 30 | Bots with more tools than this load the rest on demand. 0 turns it off. |
CHATGPT_SIGN_IN | auto (on) | auto, on or off. Lets people use their ChatGPT plan instead of an API key. Each plan serves only its owner. auto is on unless billing is on. See Connect a ChatGPT plan. |
RUN_CONCURRENCY | 20 | How many runs one worker processes at once. See Scaling. |
AI_GATEWAY_URL | (empty) | Send model calls through Cloudflare AI Gateway: https://gateway.ai.cloudflare.com/v1/<account>/<gateway>. |
AI_GATEWAY_TOKEN | (empty) | Token for an authenticated gateway, sent as cf-aig-authorization. |
GOOGLE_AI_API_KEY | (empty) | A server-wide Google AI key: live calls in workspaces without a Gemini or OpenAI key of their own use it. You pay Google for those calls. |
With AI_GATEWAY_URL set, calls for OpenAI, Anthropic, Google, xAI and OpenRouter keys go through the gateway, for caching, logs and rate limits. A credential with its own base URL keeps it.
Local models. To use Ollama running on the server, allow the server to reach it with OUTBOUND_ALLOW_CIDRS, then add it as an OpenAI-compatible credential with the address the worker container can reach. On Docker Desktop that's host.docker.internal:
casama credential add --provider openai_compatible --base-url http://host.docker.internal:11434/v1On Linux, use the host's LAN address instead (for example http://192.168.1.20:11434/v1).
Object storage
Computers' home folders are archived to object storage when they sleep, and checkpoints are kept there too. By default the supervisor stores them on the objects Docker volume, which needs nothing extra on one host.
For S3-compatible storage (SeaweedFS from the s3 profile, Cloudflare R2, AWS S3 and others), the supervisor reads these settings:
| Name | Default | What it does |
|---|---|---|
OBJECT_STORE | (filesystem) | s3 to use S3-compatible storage. |
OBJECT_STORE_DIR | /data/objects | Folder for the filesystem store. |
S3_BUCKET | Required with s3 | Bucket name. |
S3_ENDPOINT | (AWS) | Endpoint, for example http://casama-s3:8333 or https://<account>.r2.cloudflarestorage.com. |
S3_REGION | (empty) | Region, for example auto for R2. |
S3_ACCESS_KEY_ID | (empty) | Access key. The s3 profile also creates SeaweedFS's user with it. |
S3_SECRET_ACCESS_KEY | (empty) | Secret key. |
S3_PREFIX | (empty) | Key prefix inside the bucket. |
S3_CREATE_BUCKET | (off) | true creates the bucket at start. |
Warning: The bundled compose file doesn't pass these to the supervisor
Only
S3_ACCESS_KEY_IDandS3_SECRET_ACCESS_KEYreach thes3service. To switch the supervisor to S3, add the settings to thesupervisorservice'senvironment:ininfra/compose/docker-compose.yml, as shown in Advanced settings. Switching stores doesn't move existing archives, so do it before computers have slept, or copy theobjectsvolume's contents to the bucket yourself.
With SeaweedFS on the same host:
# infra/compose/.env
S3_ACCESS_KEY_ID=casama
S3_SECRET_ACCESS_KEY=a-long-random-secret# infra/compose/docker-compose.yml, under services.supervisor.environment
OBJECT_STORE: s3
S3_ENDPOINT: http://casama-s3:8333
S3_BUCKET: casama
S3_CREATE_BUCKET: "true"
S3_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID:-}
S3_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY:-}Then start it with the profile:
docker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env --profile s3 up -dcasama selfhost backup archives the objects volume only. With S3, back up the bucket with your storage provider's tools.
The Library's files
The API and worker keep a second store: files bots hand over in replies, which the Library keeps with their versions, and the pictures, videos and sounds in chats. By default it's the library Docker volume, mounted at /data/library. To keep it in S3-compatible storage instead, set these in infra/compose/.env; Compose passes them to the API and worker:
| Name | Default | What it does |
|---|---|---|
LIBRARY_OBJECT_STORE | (filesystem) | s3 to use S3-compatible storage. |
LIBRARY_OBJECT_DIR | /data/library | Folder for the filesystem store. |
LIBRARY_S3_BUCKET | Required with s3 | Bucket name. |
LIBRARY_S3_ENDPOINT | (AWS) | Endpoint, for example an R2 address. |
LIBRARY_S3_REGION | auto | Region. |
LIBRARY_S3_ACCESS_KEY_ID | (empty) | Access key. |
LIBRARY_S3_SECRET_ACCESS_KEY | (empty) | Secret key. |
LIBRARY_S3_PREFIX | library/ | Key prefix inside the bucket. |
The scheduled backup container includes the library volume (library.tar.gz). casama selfhost backup doesn't; see Back up your server.
Computers and sandbox
These go to the supervisor. Hosted providers and their settings are on Computer providers.
| Name | Default | What it does |
|---|---|---|
COMPUTER_MEMORY_MB | 2048 | Memory for each new computer, in MB. Swap is capped at the same amount. The API also counts a computer with no recorded size as this much. |
COMPUTER_HOST_MEMORY_GB | Set by the installer | Memory all hosted computers together may use, in GB. A start past it waits with capacity_full. The installer sets the machine's memory less 4 GB (at least 2). 0 means no limit. See Server capacity. |
WARM_POOL_SIZE | 0 (off) | How many started headless computers to keep waiting, so a new computer starts at once. Docker provider only. |
SANDBOX_RUNTIME | Set by the installer | The Docker runtime for computers: runsc for gVisor, or empty for Docker's default. |
Network and egress
| Name | Default | What it does |
|---|---|---|
OUTBOUND_ALLOW_CIDRS | (empty) | Private networks the API and worker may call, comma-separated CIDRs, for example 192.168.1.0/24. Everything private is blocked otherwise. |
TURN_PUBLIC_HOST | Set by the installer | The host name viewers use to reach the TURN relay. The domain, or localhost for --local. |
TURN_HOST_PORT | 3478 | Host port the TURN relay is published on, and the port viewers are given. "Run Casama on this computer" moves it when 3478 is taken. |
TURN_BIND | 0.0.0.0 | The address the TURN port listens on. --local sets 127.0.0.1. |
OUTBOUND_ALLOW_CIDRS covers calls the server makes for bots and people: model endpoints such as Ollama, password managers such as Vaultwarden, connections, MCP servers and memory backends. It doesn't change what computers can reach. The egress proxy always blocks private, loopback, link-local (cloud metadata), CGNAT, multicast and reserved addresses for computers.
Voice and phone calls
Bots phoning other numbers through a workspace's own Twilio account is built but turned off for now. To try it, set PHONE_CALLS=true on the server (bots get the voice.call tool) and build the app with --dart-define=PHONE_CALLS=true (admins see Workspace settings → Phone calls). It needs a public https:// address, because Twilio calls back to PUBLIC_API_URL (Compose sets it to CASAMA_PUBLIC_URL).
To ring iPhones for calls through PushKit, the worker needs an APNs token key for the app's bundle:
| Name | Default | What it does |
|---|---|---|
APNS_KEY_P8 | (empty) | The APNs token key: the .p8 file's contents. |
APNS_KEY_ID | (empty) | The key's id. |
APNS_TEAM_ID | (empty) | Your Apple team id. |
APNS_VOIP_TOPIC | ai.casama.app.voip | The app's VoIP push topic. |
Push notifications
| Name | Default | What it does |
|---|---|---|
FCM_SERVICE_ACCOUNT | (empty) | A Firebase service account JSON, on one line, for the Firebase project the apps are built with. Unset: no push. |
Push only reaches apps built with the same Firebase project as the service account. Without push, the in-app inbox still shows every notification.
The apps from the App Store and Google Play are built with Casama's Firebase project, so your own key can't reach them. Link the server to Casama Cloud instead and, as long as FCM_SERVICE_ACCOUNT is empty, its notifications and call rings go through there, for free: casama selfhost remote on for a server on your own computer, or casama selfhost remote link for one with its own domain. With Private Notifications on, they carry no text. See Use your server on your phone.
Integrations
| Name | Default | What it does |
|---|---|---|
GOOGLE_OAUTH_CLIENT_ID | (empty) | Your Google OAuth client, for Gmail, Calendar and Drive connections. |
GOOGLE_OAUTH_CLIENT_SECRET | (empty) | Its secret. |
MCP_OAUTH_CLIENTS | (empty) | OAuth clients for apps that don't support automatic registration, as JSON by app id: {"slack":{"client_id":"...","client_secret":"..."}}. |
COMPOSIO_API_KEY | (empty) | A server-wide Composio key. Apps whose own sign-in needs a client the server doesn't have (GitHub, Slack, Asana, Google's apps without a Google client, and others) then offer Sign in through Composio. The admin console's Services tab can switch back to people's own accounts. |
OAUTH_REDIRECT_URL | <PUBLIC_API_URL>/oauth/callback | Where vendors send people back after an app sign-in. Change it only if vendors must use another address. |
SEARXNG_URL | (empty) | A SearXNG instance for web search in workspaces without a Brave Search or Tavily key. Free: ./install.sh --search runs one (http://searxng:8080). Its settings must allow JSON results. |
UNSPLASH_ACCESS_KEY | (empty) | Wallpaper photo search in Appearance. Without it, the app offers its own patterns and photos. |
GALLERY_URL | https://gallery.casama.ai | The open gallery of themes, color schemes, wallpapers, skills, apps, starter bots, routine ideas and reviewed plugins. Set to off to turn it off; a fork can point here instead. When it can't be reached, the built-in looks, skills, apps and bots stay. |
Register https://casama.example.com/oauth/callback as the redirect URI in each OAuth app. See Connections.
Gallery
The gallery's settings beyond GALLERY_URL. The defaults suit almost every server.
| Name | Default | What it does |
|---|---|---|
GALLERY_SIGNATURE | optional | Whether the gallery must be signed. required: the server only trusts a catalog whose manifest.sig checks out against the public key, and shows the gallery as unavailable otherwise. optional: it checks the signature when the catalog has one (a signature that doesn't check out still makes it unavailable). off: never checked. With no public key, it's off. |
GALLERY_PUBLIC_KEY | (empty) | The catalog's Ed25519 public key, base64 of the raw 32 bytes. Empty: Casama's own key for the default GALLERY_URL, none for any other address. Set it when you sign your own catalog (GALLERY_SIGNING_KEY in its CI). |
GALLERY_SOURCES | (empty) | More catalogs next to the main one, comma-separated: url, name=url, or name=url#<base64 public key>. Their items show up with ids like team:weekly-review. Each folder is laid out like the gallery's and checked with the same node gallery/check.mjs. If one can't be reached, only its items are missing. |
GALLERY_STATS_URL | https://api.casama.ai/v1/gallery/stats | Where the "Used by 120 people" numbers on gallery items come from. They're Casama's public, aggregate counts (nothing under 10 people is shown). off hides them. Your server's own installs aren't sent anywhere. |
GALLERY_SUBMIT_REPO | stackwares/casama-gallery | Where Submit to the gallery opens pull requests (owner/repo). |
GALLERY_SUBMIT_TOKEN | (empty) | A GitHub token that can push branches and open pull requests on that repository. Empty: Submit to the gallery is off on this server. |
GALLERY_REWARDS | {"50":10,"250":25,"1000":75} | Casama Cloud only (billing on): credits for people whose submitted item reaches that many active users, as JSON (active users → credits). Each item earns each one once. off turns rewards off. |
An offline server can read a local copy: point GALLERY_URL at a folder you serve, made with casama gallery mirror <dir>, which checks the signature as it downloads.
Billing
Billing is for Casama Cloud. The bundled compose file sets BILLING_ENABLED=false for the API and worker, so there's no paywall and no usage limit, and none of the payment settings apply. Settings whose auto follows billing keep their self-hosted behaviour: ABUSE_CONTROLS, HEALTH_REQUIRES_ENCRYPTION and REFERRALS stay off, and CHATGPT_SIGN_IN stays on.
Computer time is recorded at what it costs whoever runs it: E2B and Daytona at their published prices, Docker at a share of the server. Change the prices with COMPUTER_RATES, as JSON by provider (docker, e2b, daytona, local, casama-cloud), in USD per vCPU-hour and per GB-hour: {"docker":{"cpu_hour":0.003,"gb_hour":0.005}}.
Settings only Casama Cloud uses
The server reads these, and the compose file passes most of them, but they only do something with BILLING_ENABLED=true. Leave them empty on your own server.
| Names | What they're for |
|---|---|
DODO_*, REVENUECAT_* | Payments on the web, and in the App Store and Google Play |
REFERRALS, REFERRAL_REWARD_USD, REFERRAL_WELCOME_USD, REFERRAL_REWARD_CAP, REFERRAL_REDEEM_DAYS, REFERRAL_LINK_BASE | Invite-a-friend credits |
SIGNUP_PROOFS, SIGNUP_POW_DIFFICULTY, APP_CHECK_PROJECT_NUMBER | Sign-up abuse controls |
CASAMA_LINK_CLOUD | Serving Casama Link to other servers (on by default when billing is on) |
CLOUD_MODEL_UPSTREAM_URL, CLOUD_MODEL_UPSTREAM_KEY, CLOUD_MODEL_MARKUP, CLOUD_COMPUTER_USD_PER_HOUR | What linked servers' model calls and computers go to and cost |
CASAMA_LINK_ZONE, CASAMA_LINK_CF_ACCOUNT_ID, CASAMA_LINK_CF_ZONE_ID, CASAMA_LINK_CF_API_TOKEN | The zone and Cloudflare account that hold linked servers' addresses and tunnels |
CASAMA_LINK_SIGN_IN_URL | Where a workspace admin approves a link code (default <PUBLIC_APP_URL>/link) |
CASAMA_LINK_PARKING, CASAMA_LINK_PARK_AFTER_DAYS | Removing tunnels of servers that stopped checking in (off, dry-run or on; after 14 days) |
CASAMA_LINK_TUNNEL_ALERT, CASAMA_LINK_RECORD_LIMIT | When the instance owners are warned about tunnel and DNS record counts (700 tunnels, 200 records) |
CASAMA_LINK_TURN_KEY_ID, CASAMA_LINK_TURN_API_TOKEN | The relay for live view away from the computer (Cloudflare's TURN service) |
TREG_API_KEY, TREG_RESALE | Paid data resale through Treg |
SUPPORT_INBOX, SUPPORT_ASSISTANT, SUPPORT_MODEL, SUPPORT_DAILY_USD, SUPPORT_MESSAGES_PER_DAY, DOCS_URL | Help & support: where messages from the app go (default support@casama.ai, sent with your email settings) and the free support assistant, which runs on CLOUD_MODEL_UPSTREAM_KEY (model, daily spending cap $10, 60 messages a person a day, docs it refreshes from) |
ABUSE_INBOX | Where reports from inside the app are emailed (default abuse@casama.ai); they also show in Admin console > Reports |
ACCOUNT_EMAILS, EMAIL_POSTAL_ADDRESS | Emails about plans and purchases (trial ending, payment failed, plan ended, credits low) and a short welcome series. Welcome and tips emails go out only when EMAIL_POSTAL_ADDRESS is set, and each has a one-click unsubscribe |
Casama Link
Casama Link connects your server to a Casama Cloud workspace. See the Casama Link overview.
| Name | Default | What it does |
|---|---|---|
CASAMA_CLOUD_URL | (empty) | Casama Cloud's address: https://api.casama.ai. |
CASAMA_CLOUD_KEY | (empty) | The server's Casama Link key (kcc_...). Empty: Casama Link is off. |
With both set:
- notifications go through Casama Cloud when the key can send them and
FCM_SERVICE_ACCOUNTis empty; - the
casama-cloudcomputer provider is available, if the key has thecomputersscope; - a workspace can add an OpenRouter model key whose base URL is
<cloud>/link/v1/modelsand whose key is the Casama Link key, if the key has themodelsscope.
See Cloud computers and credits.
Remote access. casama selfhost remote on (or Use on Your Phone in the desktop app) writes the settings below along with the two above, and changes the address and sign-up settings. Don't set these by hand; see What gets set.
| Name | Default | What it does |
|---|---|---|
CASAMA_REMOTE_ACCESS | off | on: the server keeps a public address through Casama Link, the connector container runs (Compose profile link) and the turn container forwards to Casama Cloud's relay. |
CASAMA_INSTANCE_ID | (empty) | This server's id at Casama Cloud. The same id gets the same address. |
CASAMA_LOCAL_URL | (empty) | The address on the server's own computer, which its own app keeps using. |
SIGNUP_INVITED_ONLY | (empty) | true: only an email address with a pending workspace invite can make an account. Needs the sign-up hook. |
CASAMA_LINK_RELAY_UPSTREAM | turn.cloudflare.com:3478 | Where the turn container forwards bots' computers for live view away from the computer. It must match Casama Cloud's relay. |
Compose also sets CASAMA_LINK_TOKEN_FILE (/link/token, where the API keeps the connector's secret on the link volume) and CONNECTOR_URL (http://connector:2000, the connector's readiness check) for the API.
Telemetry and observability
| Name | Default | What it does |
|---|---|---|
TELEMETRY | off | on sends anonymous counts once a week (see below). |
TELEMETRY_URL | https://telemetry.casama.ai/v1/ping | Where telemetry goes. |
ERROR_REPORTING | auto | auto (Sentry if SENTRY_DSN is set, else PostHog if POSTHOG_API_KEY is set, else nothing), sentry, posthog or none. |
SENTRY_DSN | (empty) | A Sentry-protocol DSN: sentry.io, self-hosted Sentry or GlitchTip. |
POSTHOG_API_KEY | (empty) | PostHog project key for error reports (and for product analytics when PRODUCT_ANALYTICS=on). |
PRODUCT_ANALYTICS | off | on sends product events and daily summaries to your PostHog project (Casama Cloud turns it on). Needs POSTHOG_API_KEY. People and workspaces that opted out are skipped. |
ANALYTICS_ENVIRONMENT | (NODE_ENV) | The environment tag on analytics and error events: production, staging or development. |
POSTHOG_PERSONAL_API_KEY | (empty) | Optional. A PostHog personal API key with person write scope: when an account is purged, its PostHog person and events are deleted too. |
POSTHOG_PROJECT_ID | (empty) | The PostHog project the key above belongs to. |
POSTHOG_APP_HOST | https://us.posthog.com | PostHog's app address for person deletion (your region or self-hosted address). |
POSTHOG_HOST | https://us.i.posthog.com | PostHog's ingest address, for another region or a self-hosted PostHog. |
LOG_LEVEL | info | The API and worker's log detail: debug, info, warn or error. |
OTEL_EXPORTER_OTLP_ENDPOINT | (empty) | Send traces to an OpenTelemetry collector. |
LANGFUSE_BASE_URL | (empty) | Langfuse address. With all three Langfuse settings, runs send LLM traces (workspaces can opt out). |
LANGFUSE_PUBLIC_KEY | (empty) | Langfuse public key. |
LANGFUSE_SECRET_KEY | (empty) | Langfuse secret key. |
METRICS_TOKEN | Generated | Bearer token for Prometheus metrics at /metrics. Without it, /metrics is off in production. |
Telemetry is off unless you turn it on. With TELEMETRY=on, the worker sends once a week a random instance id, the Casama version and two numbers: bots and users active in the last 7 days. Nothing else: no names, emails, content, keys or addresses.
Error reports are scrubbed before they leave: request bodies, headers, cookies and users are dropped, and secret-looking values and emails are redacted.
Backups and alerts
These are read by the optional backup and monitoring profiles, not by the server. They're explained on Operations.
| Name | What it does |
|---|---|
CASAMA_BACKUPS | on once you installed with --backups, so re-running the installer keeps the backup profile. |
BACKUP_* | Where and when the backup container uploads. See Off-site backups. |
ALERT_EMAIL | Where Alertmanager emails alerts, through the SMTP settings above. See Alerts. |
CASAMA_BACKUP_RECIPIENTS | Read by casama selfhost backup from your shell, not from .env: age recipients for --encrypt. |
Secret store
Bots' named secrets live in Supabase Vault in your database by default. A workspace admin can keep them in Infisical instead, under workspace settings → Where secrets are kept, with a machine identity's client id and secret. There's no server setting for it. Casama's other credentials (model keys, connection tokens) stay in Vault either way.
Encryption keys
Encryption at rest seals message content, run events, memories, summaries, ticket text, pages and knowledge in Postgres. It's off by default and turned on per workspace by its owners, once the server has a key.
| Name | Default | What it does |
|---|---|---|
CONTENT_ENCRYPTION_KEY | (generated) | The server key that wraps workspace keys: 32 bytes, base64. install.sh makes one unless KMS is set; back it up. |
CONTENT_ENCRYPTION_KEY_PREVIOUS | (empty) | Older keys during a rotation, comma-separated. |
CONTENT_KMS_KEY_ID | (empty) | Use AWS KMS instead: the key's id or ARN. |
CONTENT_KMS_REGION | (empty) | The KMS key's region. |
AWS_ACCESS_KEY_ID | (empty) | AWS credentials for KMS. |
AWS_SECRET_ACCESS_KEY | (empty) | AWS credentials for KMS. |
AWS_SESSION_TOKEN | (empty) | Optional session token for temporary credentials. |
HEALTH_REQUIRES_ENCRYPTION | auto (off) | on stores health data only for workspaces with encryption at rest on. |
Danger: Back up the key
Without the key, encrypted content can't be read. Keep a copy somewhere other than the server.
Rotate the server key:
- Generate a new key with
openssl rand -base64 32. - Move the current value to
CONTENT_ENCRYPTION_KEY_PREVIOUSand put the new key inCONTENT_ENCRYPTION_KEY. - Run
casama selfhost up. - Wait at least an hour. The worker's hourly maintenance rewraps every workspace key that still uses the old server key. Owners can also rotate their workspace right away under workspace settings.
- Remove
CONTENT_ENCRYPTION_KEY_PREVIOUSand runcasama selfhost upagain.
Rotation rewraps workspace keys and people's About you keys; it doesn't rewrite rows. Search can't look inside sealed text: memory and knowledge search use embeddings only, which stay unencrypted.
If the database leaked: rotating the server key isn't enough, because a copy of the database plus the old server key still opens the old data keys. Replace the data keys as well:
- Rotate the server key as above.
- As the instance owner, call
POST /v1/admin/encryption/replace-keys. It replaces every workspace's data key and every person's About you key. A workspace owner can do the same for one workspace withPOST /v1/orgs/{id}/encryption/replace-key. - The worker re-encrypts every row onto the new keys in the background, 500 rows per column a minute. Rows are decrypted and encrypted again in the server, never in Postgres, and keep reading normally the whole time. The workspace's encryption status shows
rekeying: trueuntil it's done. - An old key is deleted 15 minutes after its last row moves, once nothing anywhere in the database still holds a value encrypted with it.
Content in the leaked copy stays readable to whoever has it; replacing keys protects everything from then on.
Audit forwarding and enterprise features
| Name | Default | What it does |
|---|---|---|
CASAMA_LICENSE_KEY | (empty) | A Casama Enterprise license key. Unlocks SAML SSO, audit log export and audit-log forwarding. |
Everything outside the ee/ folder works without a license. See Audit-log forwarding.
Privacy and retention
| Name | Default | What it does |
|---|---|---|
ACCOUNT_DELETION_GRACE_DAYS | 7 | Days between an account deletion request and the purge (0 to 30). |
Deleted accounts are purged with the workspaces they solely own and their computer snapshots. Run events are kept for each workspace's retention setting (default 180 days). See Privacy.
Advanced settings
The server and supervisor read these, but the bundled compose file doesn't pass them through. On Helm, set them with extraEnv; on a platform, as environment variables. With Compose, add them to the service's environment: in infra/compose/docker-compose.yml. The API and worker share the x-casama block at the top:
x-casama: &casama
# ...
environment: &casama-env
# ...
EMBEDDINGS: ${EMBEDDINGS:-auto}Then set the value in .env and run casama selfhost up. Keep your edit when you upgrade: git pull refuses to overwrite a changed file, so commit it on a local branch or re-apply it.
API and worker:
| Name | Default | What it does |
|---|---|---|
LOCAL_COMPUTERS | true | People's own machines as bot computers through the desktop companion. |
EMBEDDINGS | auto | auto embeds memories with the workspace's OpenAI key when it has one; none uses full-text search only. |
AI_GATEWAY_PROVIDERS | (all) | Limit AI Gateway to some providers, comma-separated: openai, anthropic, google, xai, openrouter. |
TRACE_URL_TEMPLATE | (empty) | A trace viewer link containing {trace_id}, shown on run timelines. |
TURN_TLS_PORT | (empty) | Also offer a turns: address on this port. The bundled relay doesn't serve TLS. |
CONTENT_KMS_ENDPOINT | (AWS's) | A custom KMS endpoint, for example a VPC endpoint. |
MODEL_PRICES_URL | OpenRouter's model list | Where the worker reads model prices once a day, for the cost shown on runs and budgets. off uses only the built-in table. |
GEMINI_LIVE_MODEL | gemini-3.8-live | The Gemini Live model for live calls (used when a workspace has a Google AI key). |
PDF_CHROMIUM_PATH | (empty: PDF export off) | A Chromium binary in the API's own image, used when PDF_RENDERER_URL is empty. Chromium can't keep its sandbox in a normal container, so prefer the sidecar. |
COMPOSIO_WEBHOOK_SECRET | (empty) | The signing secret of a Composio webhook subscription to <PUBLIC_API_URL>/hooks/composio. With it, new mail and calendar changes in Composio-connected apps start a bot's check-in scan early; without it, scans keep their schedule. |
SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, SLACK_SIGNING_SECRET | (empty: paste a bot token) | A Slack app of your own for one-click install of bots into Slack workspaces. Without them, people connect Slack with a bot token. See Chat apps. |
Supervisor:
| Name | Default | What it does |
|---|---|---|
COMPUTER_CPUS | 1 | CPUs for each new computer. |
DEFAULT_PROVIDER | docker | The provider for computers that ask for the default. See Computer providers. |
STREAM_IDLE_STOP_MS | 60000 | How long the live view streamer keeps running after the last viewer leaves. |
OBJECT_STORE, S3_* | Filesystem | See Object storage. |
| Provider settings | (none) | See Computer providers. |
Egress proxy:
| Name | Default | What it does |
|---|---|---|
EGRESS_BLOCKED_CIDRS | (empty) | More address ranges to block for computers, on top of the built-in private ranges. |
For tests and development only. The server also reads names that point it at fakes or record model calls. Never set them on a real server: APP_CHECK_JWKS_URL, APP_CHECK_ISSUER_BASE, APNS_URL, CASAMA_LICENSE_PUBLIC_KEY, CASAMA_LINK_CF_API_URL, CASAMA_LINK_TURN_API_URL, CASAMA_MAX_OUTPUT_TOKENS, CASAMA_MODEL_FIXTURES, CASAMA_MODEL_RECORD, CHATGPT_API_URL, CHATGPT_AUTH_URL, COMPOSIO_API_URL, DODO_API_URL, GITHUB_API_URL, REVENUECAT_API_URL, SLACK_API_BASE, STRIPE_API_URL, TREG_API_URL, TWILIO_API_URL and UNSPLASH_API_URL. FFMPEG_PATH, SKILLS_CATALOG_DIR and the supervisor's EGRESS_PROXY_PORT and NAME_PREFIX are set inside the images or by Compose; leave them alone.