ddev-litellm

A DDEV add-on that runs a LiteLLM proxy as a DDEV service, enabling local AI model testing with Drupal’s ai_provider_litellm module.

Services

The add-on starts two containers via a single docker-compose.litellm.yaml:

LiteLLM uses Prisma as its ORM and requires PostgreSQL — key management endpoints (/key/info, /key/generate) will not work without it.

Features

• LiteLLM proxy accessible inside DDEV at http://ddev-<project>-litellm:4000
• PostgreSQL sidecar started and health-checked automatically before LiteLLM
• Pre-configured to connect to Ollama running on the host machine
• Optional vLLM / HuggingFace endpoint support
• On each ddev start: waits for LiteLLM readiness, creates a Drupal virtual key in the DB, and auto-sets ai_provider_litellm.settings.host via drush

Requirements

• DDEV ≥ 1.24.10
• Ollama installed on your host machine (for Ollama backend)
• At least one Ollama model pulled: ollama pull llama3.2

Installation

ddev add-on get credevator/ddev-litellm
ddev restart

Usage

Service URLs

Commands

ddev litellm              # Show service status
ddev litellm open         # Open LiteLLM UI in browser
ddev litellm logs         # View service logs
ddev litellm-models       # List available models

Configuring Models

Edit .ddev/litellm_config.yaml to add or modify model backends, then run ddev restart.

Ollama (default, connects to host machine port 11434):

- model_name: ollama/llama3.2
  litellm_params:
    model: ollama/llama3.2
    api_base: http://host.docker.internal:11434

vLLM / HuggingFace (uncomment in litellm_config.yaml and set VLLM_API_BASE):

# In .ddev/config.yaml:
# web_environment:
#   - VLLM_API_BASE=http://host.docker.internal:8000

Configuring Drupal

On each ddev start the add-on automatically:

1. Waits for the LiteLLM proxy to be ready
2. Creates a virtual API key sk-drupal-dev-key in the LiteLLM database (safe to run repeatedly — no-op if it already exists)
3. Sets ai_provider_litellm.settings.host to http://ddev-<project>-litellm:4000 via drush

You still need to wire up the API key in Drupal once:

1. Go to Configuration → Key (/admin/config/system/keys)
2. Add a key named litellm_key with value sk-drupal-dev-key
3. Go to Configuration → AI → Providers (/admin/config/ai/providers/litellm)
4. Select litellm_key under API Key

Keys: master vs. virtual

To override the master key, add to .ddev/config.yaml:

web_environment:
  - LITELLM_MASTER_KEY=sk-your-custom-key

Note: if you change the master key after first start, update the key/generate call in .ddev/config.ddev-litellm.yaml to match.

Troubleshooting

LiteLLM takes a while to start — the image is ~2GB. PostgreSQL must be healthy first, then LiteLLM runs Prisma migrations before serving requests. The healthcheck allows up to 5 minutes (30s interval × 10 retries + 120s start_period). Check progress with ddev litellm logs.

Cannot reach Ollama — ensure Ollama is running on the host (ollama serve) and the model is pulled (ollama pull llama3.2).

Port 4000 or 4001 conflict — edit HTTP_EXPOSE / HTTPS_EXPOSE in .ddev/docker-compose.litellm.yaml.

Linux users — host.docker.internal is injected via extra_hosts: host.docker.internal:host-gateway. This is handled automatically; macOS and Windows Docker Desktop provide it natively.

PostgreSQL data — key data persists in a Docker named volume (litellm-postgres-data). If you need a clean slate: docker volume rm <project>_litellm-postgres-data then ddev restart.

Uninstalling

ddev add-on remove ddev-litellm
ddev restart

Note: .ddev/litellm_config.yaml is preserved on removal. Delete it manually if no longer needed. The litellm-postgres-data Docker volume is also preserved — remove it manually with docker volume rm <project>_litellm-postgres-data.

License

Apache 2.0