Skip to content

Installation

Use this guide to run DeltaLLM locally for development, evaluation, or contribution. It covers the backend API, PostgreSQL schema, optional Redis, and the admin UI.

Choose your path

  • Use Docker Compose if you want the fastest working setup with PostgreSQL and Redis included.
  • Use this page if you want a full local installation for development, debugging, or contributing.

Most developers should start with Docker Compose

The Docker setup is the quickest route to a working DeltaLLM instance. This page is intentionally focused on the manual local install path.

Requirements

Before you begin, make sure you have:

  • Python 3.11 or later
  • Node.js 20 or later
  • PostgreSQL 15 or later
  • Redis 7 or later (optional for local development, recommended for production)
  • At least one provider API key such as OpenAI, Anthropic, Azure OpenAI, or Groq

1. Clone the repository

git clone https://github.com/deltawi/deltallm.git
cd deltallm

2. Install backend dependencies

The project includes a uv.lock file, so uv is the recommended installer.

uv sync --dev

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

The backend commands below use uv run .... If you installed with pip, run the same commands without the uv run prefix.

3. Configure environment variables

  1. Create an empty PostgreSQL database.
  2. Export the variables necessary for DeltaLLM startup.

Generate the master key and salt key before you start

DeltaLLM will not start with placeholder values such as change-me. You must generate both a unique DELTALLM_MASTER_KEY and a unique DELTALLM_SALT_KEY.

Copy and run:

export DELTALLM_MASTER_KEY="$(python3 -c 'import secrets; print(\"sk-\" + secrets.token_hex(20) + \"A1\")')"
export DELTALLM_SALT_KEY="$(openssl rand -hex 32)"

DELTALLM_MASTER_KEY must be at least 32 characters long and include both letters and numbers. DELTALLM_SALT_KEY must be a real secret value and must not be change-me.

export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/deltallm"
export OPENAI_API_KEY="sk-your-provider-key"
export PLATFORM_BOOTSTRAP_ADMIN_EMAIL="admin@example.com"
export PLATFORM_BOOTSTRAP_ADMIN_PASSWORD="replace-with-a-strong-password"

Keep the generated DELTALLM_MASTER_KEY and DELTALLM_SALT_KEY from the previous command. Replace the database address, provider key, email, and password with your own values.

OPENAI_API_KEY is used by the sample model in config.example.yaml. If you plan to use a different provider, update config.yaml in the next step to match that provider's credentials and base URL.

Redis is optional for local development. If Redis is available, also export:

export REDIS_URL="redis://localhost:6379/0"

Without Redis, DeltaLLM can still start locally, but readiness checks may report a degraded status until Redis is configured.

4. Create your local config

Copy the example config and point the application at it:

cp config.example.yaml config.yaml
export DELTALLM_CONFIG_PATH=./config.yaml

The example config is ready for a quick local start:

  • It defines a sample gpt-4o-mini deployment
  • It reads secrets from environment variables instead of hardcoding them
  • It adds the sample model to the database on the first start
  • It uses model_deployment_source: db_only, so later changes come from the Admin UI or API
  • It keeps advanced features such as email, SSO, and governance notifications commented until you need them

After the first successful start, set model_deployment_bootstrap_from_config to false in config.yaml. This prevents later restarts from trying to import the sample again.

If you want to route to a different model or provider, edit config.yaml now. See the model configuration guide for the full reference.

When you are ready for more than the minimum setup:

  • uncomment the email block to enable invitation emails, password reset, admin test email, and governance notifications
  • uncomment the SSO block only after Redis and your identity provider settings are ready
  • leave governance notifications disabled until email delivery is configured

5. Initialize Prisma and apply the database schema

Generate the Prisma client artifacts, fetch the required binaries, and apply the schema to your local database:

uv run prisma generate --schema=./prisma/schema.prisma
uv run prisma py fetch
uv run prisma db push --schema=./prisma/schema.prisma

6. Start the backend API

uv run uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

DeltaLLM is now available at http://localhost:8000.

Useful endpoints:

  • Liveliness: http://localhost:8000/health/liveliness
  • Readiness: http://localhost:8000/health/readiness
  • OpenAI-compatible API: http://localhost:8000/v1

7. Start the admin UI

In a second terminal:

cd ui
npm ci
npm run dev

The admin UI runs at http://localhost:5000 and proxies API requests to the backend on port 8000.

8. Verify the installation

Check that the service is live:

curl http://localhost:8000/health/liveliness

You should receive:

{
  "status": "ok"
}

List the available models:

curl http://localhost:8000/v1/models \
  -H "Authorization: Bearer $DELTALLM_MASTER_KEY"

If this list is empty, confirm that model_deployment_bootstrap_from_config was true for the first start. You can also create a deployment from the Admin UI.

After a model is available, continue to Send your first request.

Optional: serve the built UI from the backend

For a single-process local preview, build the UI and let the backend serve it:

cd ui
npm run build
cd ..
uv run uvicorn src.main:app --host 0.0.0.0 --port 5000

In this mode, the backend serves both the API and the built frontend on http://localhost:5000.

Next steps