---
title: Run It Locally
description: Three ways to spin up the docs site (with the Oracle) on your own machine.
---

The docs site — and the Oracle that lives in the corner — is just an Astro app. You can run it three ways depending on what you have at hand.

## Option A — Astro dev server, neuronetz.ai backend (fastest)

The Oracle calls your shared Ollama at `https://api.neuronetz.ai`. No local GPU needed, no API keys to manage.

```bash
cd /home/stephan/PhpstormProjects/Nibiru/docs

# .env (copy from .env.example, defaults already point at neuronetz.ai)
cp .env.example .env

npm install      # one-time
npm run dev      # http://localhost:4321
```

Open <http://localhost:4321/>. Click the amber Oracle launcher in the bottom-right and ask anything.

**Pull the embedding model once** on your Ollama host (build-time + runtime):

```bash
curl https://api.neuronetz.ai/api/pull -d '{"name":"nomic-embed-text"}'
```

Without it, the Oracle still works — it just runs in chat-only (no-RAG) mode and answers from the model's parametric knowledge. With it, answers are grounded in this documentation.

### Build the embedding index

```bash
npm run build:oracle    # writes public/oracle-index.json
```

The dev server will pick it up on the next request. Or skip this step entirely — the runtime endpoint handles a missing/empty index gracefully.

### Inspect the runtime config

The Oracle's `/api/oracle` endpoint also responds to GET with its current config (no secrets):

```bash
curl http://localhost:4321/api/oracle
# {"status":"ok","llm":{"provider":"ollama","ollamaUrl":"https://api.neuronetz.ai",
#  "model":"qwen2.5-coder:14b"},"embed":{...},"index":{...}}
```

## Option B — Docker compose, locally

Closer to production. Builds the same image you'd ship.

```bash
cd /home/stephan/PhpstormProjects/Nibiru/docs
cp .env.example .env

docker compose -f docker-compose.yml -f docker-compose.local.yml up --build
```

The `docker-compose.local.yml` override:

- Publishes `4321:4321` so the app is reachable at <http://localhost:4321/>.
- Drops the `VIRTUAL_HOST` / `LETSENCRYPT_HOST` env vars.
- Doesn't need an `nginx-proxy` network on your dev box.

The first build takes 1-2 minutes. Subsequent rebuilds are fast (Docker caches the dep layer).

## Option C — Fully offline, local Ollama

For airgapped dev, demos on a plane, or burning your own GPU.

```bash
# 1) Run Ollama on your laptop
ollama serve &

# 2) Pull a chat model (any of these works)
ollama pull qwen2.5-coder:14b      # 8 GB, recommended
# ollama pull qwen2.5-coder:1.5b   # 1 GB, faster but less accurate
# ollama pull llama3.2:3b          # 2 GB, alternative

# 3) Pull an embedding model
ollama pull nomic-embed-text

# 4) Point the docs at it
cd /home/stephan/PhpstormProjects/Nibiru/docs
cat > .env <<EOF
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_CHAT_MODEL=qwen2.5-coder:14b
OLLAMA_EMBED_MODEL=nomic-embed-text
EOF

npm run build:oracle
npm run dev
```

Now `http://localhost:4321/api/oracle` calls your laptop's Ollama. No internet required.

## Switching to Anthropic / OpenAI (if you want to)

The Oracle supports paid APIs as a fallback. In `.env`:

```bash
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

EMBED_PROVIDER=openai
OPENAI_API_KEY=sk-...
```

Useful if your Ollama is down, or for comparing answer quality across providers.

## Smoke-test cheat sheet

```bash
curl http://localhost:4321/                                    # 301 → /en/
curl -I http://localhost:4321/en/                              # 200
curl http://localhost:4321/api/oracle                          # GET = config
curl -X POST -H 'Content-Type: application/json' \
     -d '{"messages":[{"role":"user","content":"How do I create a module?"}]}' \
     http://localhost:4321/api/oracle | jq .answer
```

If the last call returns a real answer that mentions `./nibiru -m`, your stack is wired up correctly.

## Troubleshooting

**Oracle returns "the Oracle could not answer".**
The Ollama server is unreachable or the chat model isn't pulled. Verify:
```bash
curl https://api.neuronetz.ai/api/tags | jq '.models[].name'
```

**Oracle answers without citations.**
The embedding index is empty. Re-run `npm run build:oracle` after pulling `nomic-embed-text`.

**Ollama returns 404 model-not-found.**
Pull the model, e.g.:
```bash
curl https://api.neuronetz.ai/api/pull -d '{"name":"qwen2.5-coder:14b"}'
```

**`ECONNREFUSED 127.0.0.1:11434`** in option C.
Local Ollama isn't running. Start it with `ollama serve &` (or via your system service).
