Get started

Clone the repository and run the setup script

git clone https://github.com/TulipFarm/tulipfarm.git
cd tulipfarm
bash scripts/setup-dev.sh

The script prompts you to choose how to run PostgreSQL:

• Docker (default) — starts a pgvector/pgvector:pg17 container exposed on localhost:5432. No system packages are installed. This is the same image CI and production use.
• Native — installs PostgreSQL 17 + pgvector via Homebrew (macOS) or apt/yum (Linux) and starts the system service.

Either way, the script initializes your soul repository at ~/.tulipfarm/soul and generates a .env.local file with random bootstrap env config (ENCRYPTION_KEY, JWT_SECRET, WEBHOOK_SIGNING_SECRET).

For a non-interactive run (CI, scripted environments), set DB_MODE before running:

DB_MODE=docker bash scripts/setup-dev.sh

Confirm the database is accepting connections:

# Docker mode
pg_isready -h localhost -p 5432 -U tulipfarm
# Native mode
psql tulipfarm -c 'select 1'

Install dependencies and start TulipFarm

pnpm install
pnpm dev

This starts two services:

• the API on http://localhost:4010
• the web UI on http://localhost:4000

Confirm the API is healthy:

curl http://localhost:4010/health

You should see:

{ "status": "ok" }

Complete the setup wizard

Open http://localhost:4000. Because no admin exists yet, the app redirects to the setup wizard at /setup. Work through the four steps:

1. Admin account — enter an email and password. This creates the first admin and logs you in.
2. Business profile — give your instance a name and optional description.
3. LLM provider — choose a provider (Anthropic, OpenAI, Azure OpenAI, or an OpenAI-compatible endpoint), enter the credentials, and pick a model. You can skip this and configure it later in Settings → LLM Config.
4. Soul backup — optionally point the soul at a git remote for backup. You can skip this and set it up later in Settings.

After step 4, the wizard calls POST /api/v1/setup/complete and redirects to the main workspace. The setup route locks — a second browser visitor cannot create another admin through the wizard.

Give the assistant a model

You build everything else by talking to the assistant, so it needs a model to run. Open Settings → Secrets, add an API key for a provider (Anthropic, OpenAI, Azure, or any OpenAI-compatible endpoint), then open Settings → LLM and assign a model to each tier. The walkthrough is in Configure LLM providers.

Build your first resource type — by asking

Open Chat and type what you want in plain language:

Create a customer resource type with a name and an email.

The assistant confirms a couple of details and builds the type for you. There is no schema to write and no restart — the new customer table is ready the moment it finishes. Open Resources and you will see customer in the list.

This is the normal way to build in TulipFarm; see Building by chat for the full picture.

Create a record

Ask the assistant to add one:

Add a customer named Ada Lovelace with email ada@example.com.

Or open Resources → customer → New and fill in the form by hand. Either way you now have a running TulipFarm instance with a custom resource type and your first record.