---
audience: developer
summary: Run a ScaiWave server locally for development, with all dependencies.
title: Local development setup
path: tutorials/developer/local-development
status: published
---

# Local development setup

ScaiWave is a Python 3.12+ FastAPI backend plus a SolidJS frontend
wrapped by Tauri. You can run the whole thing locally; tests use
SQLite in-memory so no infrastructure is needed for those.

## Prerequisites

- Python 3.12 or newer.
- Node 20 or newer (for the client).
- Docker + Docker Compose (for the infra layer).
- (Optional) Rust toolchain if you want to build the Tauri desktop
  app.

## 1. Clone and set up the venv

```bash
git clone https://github.com/scailabs/scaiwave.git
cd scaiwave
python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e docs/integrations/scaidrive/sdk-python
```

The editable ScaiDrive SDK install is needed for the drive plugin to
work; otherwise drive-search returns an import error.

## 2. Start the infra

```bash
make docker-up
```

Spins up MariaDB, Redis, NATS JetStream, MinIO, Weaviate, and
ClamAV. Default ports are configured in `docker-compose.yml`.

Wait until `docker-compose ps` shows all services healthy.

## 3. Run migrations

```bash
make migrate
```

Applies every Alembic migration to the dev database. Idempotent.

## 4. Start the API

```bash
make dev
```

Hot-reload FastAPI on `:8000`. The default config uses
`auth_mode=mock` — sign in returns a static token without a real
ScaiKey, so you can develop without setting up identity.

Watch the logs in this terminal.

## 5. Start the worker

In another terminal:

```bash
make worker
```

ARQ async worker for background jobs: message indexing, summary
generation, scheduled tasks, sidekick timeouts.

## 6. Start the client

In another terminal:

```bash
cd client
npm install
npm run dev
```

Vite dev server on `:5173`. The dev proxy forwards `/v1/*` and
`/_scaiwave/*` to the API on `:8000`.

Open `http://localhost:5173` — you'll be auto-signed-in as the mock
dev user.

## 7. (Optional) Tauri desktop

```bash
cd client
npm run tauri:dev
```

Launches the Tauri desktop app pointing at the dev server. Native
windows, native notifications, OS-level keychain for tokens.

## Running tests

```bash
make test
```

Runs pytest with `asyncio_mode=auto`. Uses SQLite in-memory — no
infra required.

Specific file:

```bash
.venv/bin/pytest tests/unit/test_room_service.py -v
```

Specific test:

```bash
.venv/bin/pytest tests/unit/test_room_service.py::TestCreateRoom::test_dm_resolves_per_viewer -v
```

## Linting

```bash
make lint
```

Runs ruff. CI rejects unfixed lints.

## Generating a migration

After changing a SQLAlchemy model:

```bash
make migration msg="add new field to participants"
```

Alembic autogenerates a migration in `app/db/migrations/versions/`.
Review the SQL before applying.

## Where to go next

- [Authenticate with ScaiKey](/docs/scaiwave/tutorials/developer/authenticate-with-scaikey).
- [Your first REST API call](/docs/scaiwave/tutorials/developer/first-rest-api-call).
- [Reference: Configuration](/docs/scaiwave/reference/configuration) — every env var.
- [Reference: CLI](/docs/scaiwave/reference/cli).