Self-host TulipFarm

Run TulipFarm on your own infrastructure. The application reads ordinary environment variables. It has no secret-store or KMS client. You choose the secret store, and your delivery layer puts values into the environment.

Self-hosted installs send no telemetry to TulipFarm.

Read	When
Docker Compose	Install, upgrade, back up, and restore one machine
Configuration	Every setting, which service reads it, and key rotation
Configuration reference	The full variable table, generated from the settings registry
Secret stores	Supply settings from Doppler, Infisical, 1Password, Vault, Kubernetes, or a file
KMS	Encrypt settings and backups with AWS KMS, GCP KMS, Azure Key Vault, Vault Transit, or age
Models	Choose model providers, families, and knowledge embeddings
Sign-in	Configure Turnstile, Google sign-in, and email links
Email	Send sign-in links and invitations through SMTP or Azure Communication Services
GitHub	Register the GitHub OAuth App for personal GitHub accounts

Architecture

                 browser
                    │ HTTPS
                    ▼
        ┌──────────────────────┐
        │ web (Caddy)          │  static app; /v1 and /.well-known/mcp-client.json → api
        └──────────┬───────────┘
                   ▼
        ┌──────────────────────┐      ┌───────────────────────────┐
        │ api                  │─────▶│ temporal (+ temporal-ui)  │
        └──────────┬───────────┘      └─────────────┬─────────────┘
                   │                                ▼
                   │              ┌──────────────────────────────────┐
                   │              │ worker           storage-worker  │
                   │              └────────┬─────────────────┬───────┘
                   ▼                       ▼                 ▼
        ┌─────────────────────────────────────┐   ┌──────────────────────┐
        │ PostgreSQL 18 + pgvector ≥ 0.8.0     │   │ S3-compatible storage│
        └─────────────────────────────────────┘   └──────────────────────┘

Service	Role
web	Serves the built web app and proxies the API on the same origin
api	HTTP API, authentication, and chat
worker	Agent, workflow, and email-delivery activities
storage-worker	Creates and maintains isolated workspace databases
temporal	Durable workflow engine; stores its state in PostgreSQL
setup	One-shot job: creates roles, databases, keys, the bucket, and service env files

Two kinds of settings

 You provide (operator settings)          Setup generates (generated settings)
 ──────────────────────────────           ────────────────────────────────────
 POSTGRES_PASSWORD, model API keys,        role passwords, encryption keys,
 Turnstile and sign-in credentials         BETTER_AUTH_SECRET, per-service URLs
          │                                         │
   your secret store                         state.json in the generated volume
   (Doppler, SOPS + KMS, …)                  (back it up; encrypt it with KMS)
          │                                         │
          └──────────────► service environment ◀────┘

Operator settings are values only you can supply. Put them in any secret store that can export environment variables. See Secret stores.

Generated settings are created once by setup and stored in state.json. Setup rewrites each service env file from that state on every run. If you lose state.json, you lose access to encrypted workspace credentials. See Back up.

Requirements

• Docker Engine with Docker Compose v2
• A DNS name pointing at the host, with ports 80 and 443 open, for automatic HTTPS
• An Anthropic API key, or another provider from model configuration
• A Cloudflare Turnstile widget for your hostname
• At least one sign-in method: a Google OAuth client, or email through SMTP or Azure Communication Services

Current limitations

As of 17 October 2026, from the current source.

Area	Limitation
Chat attachments	Chat uploads use Cloudflare R2 only (CHAT_R2_* in packages/workspaces/src/chat-objects.ts). The Compose stack leaves them unset, so uploads are unavailable. Workspace storage works with any S3-compatible service.
Knowledge embeddings	Semantic knowledge search works with Azure Foundry or any OpenAI-compatible endpoint, but only for text-embedding-3-large at 1,536 dimensions, the size workspace storage declares. Other models need a new profile and migration. Leave KNOWLEDGE_EMBEDDINGS_ENABLED unset to keep embeddings disabled. See embedding providers.
Bot protection	Production sign-in requires real Cloudflare Turnstile keys. Test keys are rejected.
Key rotation	Encryption keys rotate through a Compose override; nothing re-encrypts old data. BETTER_AUTH_SECRET and generated passwords do not rotate. See key rotation.
Scale	The Compose stack runs on one machine. For more, use the same images and the configuration contract.