# Develop Oatmilk locally

> Run Oatmilk from source with hot reload, local data services and, if you like, local AI models.

Source: https://app.getoatmilk.com/docs/self-hosting/develop

To change Oatmilk itself, run it from source with `bun run dev`. One command starts the data services it needs in Docker, so you don't need any cloud accounts to begin.

## 1. Install what it needs

- Node.js 24 and [Bun](https://bun.sh) 1.3.14, the versions `package.json` pins.
- Docker with Compose 2.20 or newer, for the data services.

## 2. Start the data services

```bash
git clone https://github.com/AGI-Ventures-Canada/oatmilk.git && cd oatmilk
bun install
bun run self-host dev
```

`self-host dev` starts PostgreSQL, Redis, the database API and file storage in Docker, applies every migration, and writes `.env.development.local` so `bun run dev` uses them and keeps accounts locally.

- Anyone can make an account on this install.
- Your own `.env.local` is left alone, but `.env.development.local` wins over it. Delete `.env.development.local` to go back to your own settings.

## 3. Add AI models

Add one of these to `.env.local`:

```bash title=".env.local, with Ollama"
OATMILK_MODEL_PROVIDER=ollama
OATMILK_LOCAL_MODEL=qwen3.5:9b
OATMILK_LOCAL_CLASSIFIER_MODEL=tev1
OATMILK_LOCAL_CLASSIFIER_API=systemone
```

```bash title=".env.local, with hosted models"
AI_GATEWAY_API_KEY=…
```

[Use local AI models](https://app.getoatmilk.com/docs/self-hosting/local-models.md) covers LM Studio and other servers. Here Oatmilk runs on your computer itself, so the default addresses, `http://localhost:11434/v1` and `http://localhost:1234/v1`, work as they are.

## 4. Start Oatmilk

```bash
bun run dev
```

Open <http://localhost:3000>, make an account and create your company. Changes to the code reload as you save.

## 5. Use your tools against it

- **API:** create a key in **Developers › API keys** (it starts with `oat_test_`), and send requests to `http://localhost:3000/api/v1/accounting/<action>`.
- **Docs:** `http://localhost:3000/docs` uses your local address in every example.
- **MCP:** `http://localhost:3000/api/mcp`.
- **CLI:** `oatmilk login --host localhost:3000`, or from source: `bun packages/cli/src/main.ts --host localhost:3000`.

## Stop

```bash
bun run self-host dev down    # stops the data services; their data stays
```

`bun run dev` keeps using them until you delete `.env.development.local`.

## Before you send a change

```bash
bun run test
bun run typecheck
bun run lint
```

`CONTRIBUTING.md` in the repository lists the full checks.