tulipfarm docsReference
Environment variables
Every variable TulipFarm reads, with defaults and descriptions.
TulipFarm is configured through environment variables. In self-hosted installs the
installer writes these to /opt/tulipfarm/.env; in local development they live in
.env.local. The tables below cover every variable the app reads.
Required (all deployments)
| Variable | Default | Description |
|---|---|---|
DATABASE_URL | — | PostgreSQL 17 connection string. The single datastore (pgvector + pg-boss). Must allow the vector and citext extensions — the app creates them at boot. |
SOUL_PATH | — | Absolute path to the soul git repository. Must be outside the project repo — a relative or in-repo path is rejected at boot. |
ENCRYPTION_KEY | — | Base64-encoded 32-byte key for encrypting application secrets. Startup fails fast if the key is absent or not 32 bytes. Generate with openssl rand -base64 32. |
JWT_SECRET | — | Required, validated as 32-byte base64 at boot. Reserved for request signing — no feature is wired to it yet (API tokens are stored as hashes, not JWTs — see Hashing). Generate with openssl rand -base64 32. |
WEBHOOK_SIGNING_SECRET | — | Required, validated as 32-byte base64 at boot. Reserved for webhook signature verification — not yet wired (the routine webhook uses a per-trigger shared secret instead). Generate with openssl rand -base64 32. |
Headless seeding
Set all three together to skip the web setup wizard and seed the first admin
account automatically on first boot. Leave all three unset (the default for curl | bash
installs) to use the interactive browser wizard instead.
See First-run setup and boot modes for a full explanation of how the instance decides which path to take.
| Variable | Default | Description |
|---|---|---|
ADMIN_EMAIL | — | Email for the first admin account. Must be a valid email format. |
ADMIN_PASSWORD | — | Password for the first admin account. |
LLM_API_KEY | — | API key for the default LLM provider. Required alongside ADMIN_EMAIL + ADMIN_PASSWORD in production — omitting it in production causes the API to refuse to start. |
LLM_PROVIDER | anthropic | Provider for LLM_API_KEY. Accepts anthropic or openai. |
BUSINESS_NAME | — | Written to soul.yaml as businessName during headless seeding. Optional. |
BUSINESS_DESCRIPTION | — | Written to soul.yaml as businessDescription. Only used when BUSINESS_NAME is also set. |
OCI / production
Variables used by the Docker Compose stack and the production image. The installer generates and writes these; they are documented here for reference.
| Variable | Default | Description |
|---|---|---|
PUBLIC_URL | http://localhost:8080 | The externally reachable URL for this instance. Drives CORS and the cookie Secure flag. Set to an https:// URL once behind TLS. |
CORS_ORIGIN | value of PUBLIC_URL | Allowed browser origin for the API. Override only if the web UI is served from a different origin than the API. |
COMPOSE_PROFILES | bundled | Set to bundled to start the included postgres container. Set to empty (COMPOSE_PROFILES=) to use an external database (see EXTERNAL_DATASTORE). |
EXTERNAL_DATASTORE | false | Set to true when COMPOSE_PROFILES is empty and DATABASE_URL points to a managed Postgres. Suppresses the bundled container. |
POSTGRES_PASSWORD | — | Password for the bundled Postgres container. Installer-generated; not used when EXTERNAL_DATASTORE=true. |
PORT | 8080 | Port the API listens on inside the container. |
NODE_ENV | production | Runtime environment. Affects logging, cookie flags, and headless-seeding validation. |
Optional (all deployments)
| Variable | Default | Description |
|---|---|---|
SESSION_TTL_SECONDS | 604800 | Session cookie lifetime in seconds (7 days). |
VITE_PORT | 4000 | Port the web UI dev server listens on (local development only). |
SOUL_GIT_REMOTE_URL | — | Remote for the soul repository. When set, the instance clones on first boot and syncs on a schedule. Can also be set from the setup wizard, which syncs immediately. |
SOUL_GIT_CREDENTIAL | — | Credential for pushing to SOUL_GIT_REMOTE_URL (e.g. a GitHub personal access token). |
BOT_GIT_NAME | tulipfarm-bot | Git commit author name for soul writes. See Soul. |
BOT_GIT_EMAIL | tulipfarmhq@gmail.com | Git commit author email for soul writes. See Soul. |
ENCRYPTION_KEY_PREVIOUS | — | The prior ENCRYPTION_KEY during a key rotation. Decryption tries the current key first, then this one. See Secrets. |
API_TOKEN_PEPPER | — | Base64 server secret (32 bytes). When set, API tokens are hashed with HMAC-SHA256(token, pepper) instead of plain SHA-256. See Hashing. |
HOOKS_DISABLED | — | Set to true to skip resource hooks.ts execution entirely. Use to boot an instance whose hooks are failing. |
KNOWLEDGE_TRGM_FALLBACK | on | Typo-tolerance pass (pg_trgm) for lexical page search. Opt-out: set to 0 or false to turn it off. |
MARKETPLACE_SOURCE | tulipfarm/skills | The owner/repo the Skills marketplace scans by default. |