Skip to content

Installation

This guide will help you install and set up the Stimm Platform for local development and production deployment.

Prerequisites

  • Docker and Docker Compose
  • uv (for local development, optional but recommended)
  • Python 3.10 or higher (if running backend locally)
  • Node.js 18+ (if running frontend locally)

Quick Start with Docker

The easiest way to run Stimm is using Docker Compose.

# Clone the repository
git clone https://github.com/stimm/stimm.git
cd stimm

# Create environment files
cp .env.example .env
cp docker/stimm/.env.example docker/stimm/.env
cp src/front/.env.example src/front/.env

# Build and start all services
docker-compose up --build

Once the services are up, you can access:

[!NOTE] front.localhost and api.localhost should automatically resolve to 127.0.0.1 on most modern systems. If they do not, you can access the services directly via:

Local Development Setup

If you prefer to run services locally for development, follow these steps.

1. Start Supporting Services

Start the required infrastructure services (PostgreSQL, Qdrant, Redis, LiveKit, etc.) using Docker Compose:

docker compose up -d postgres qdrant traefik livekit redis sip

2. Set Up Python Environment

Using uv (recommended):

# Install dependencies
uv sync --group dev --group docs

# Set up environment files and Python path (optional)
./scripts/setup_env.sh

3. Run Backend Locally

uv run python -m src.main

The backend will be available at localhost:8001.

4. Run Frontend Locally

In a separate terminal:

cd src/front
npm install
npm run dev

The frontend will be available at localhost:3000.

Database Initialization

When starting from scratch, the PostgreSQL database needs to have its schema created. The stimm Docker image automatically runs migrations on startup (via an entrypoint script). This means you don't need to run any manual migration steps when using Docker Compose.

If you are running the backend locally (without Docker), you can run migrations manually:

uv run alembic upgrade head

After migrations are applied, the database will contain the necessary tables (agents, users, rag_configs, etc.) and a default system user.

Note: If you encounter errors about missing tables, ensure migrations have been run. You can check the current migration version with:

docker compose exec postgres psql -U stimm_user -d stimm -c "SELECT * FROM alembic_version;"

Next Steps

  • Quick Start – Run your first voice conversation.
  • Configuration – Learn about environment variables and configuration options.