# Local Setup / Lokales Setup — evOo

**DE** · Startbefehle für die lokale Programmier-Maschine.  
**EN** · Start commands for the local programming machine.

## Prerequisites / Voraussetzungen

- Node.js **≥ 22** (22.x / 24.x / 26+; not 23.x or 25.x)
- **pnpm 9** (`corepack enable && corepack prepare pnpm@9.15.0 --activate`)
- **Docker** (Postgres + optional sandboxes / Kokoro)
- Git, OpenSSL

## 1. Env

```bash
cp .env.example .env
```

Minimum secrets (use independent long random values):

| Variable | Notes |
|----------|-------|
| `POSTGRES_PASSWORD` | e.g. `openssl rand -hex 16` |
| `DATABASE_URL` | Same password; host port **5433** with postgres-host overlay |
| `BETTER_AUTH_SECRET` | long random |
| `ENCRYPTION_KEY` | long random |
| `SCREEN_PROXY_SECRET` | long random |
| `SANDBOX_SUPERVISOR_TOKEN` | required for Docker sandboxes |

Optional: `OPENROUTER_API_KEY`, Composio/Pipedream, `KOKORO_BASE_URL`.

## 2. Postgres

```bash
docker compose --env-file .env \
  -f infra/compose/docker-compose.yml \
  -f infra/compose/docker-compose.postgres-host.yml \
  up postgres -d
```

Default host URL shape:

```text
postgresql://rakazo:<POSTGRES_PASSWORD>@127.0.0.1:5433/rakazo
```

(DB role/db names may still say `rakazo` — tech debt; do not rename without migration.)

## 3. Install & migrate

```bash
pnpm install
pnpm db:generate
pnpm db:migrate
```

Optional sandbox image:

```bash
pnpm sandbox:build
```

## 4. Dev servers

```bash
pnpm dev
```

Starts API, worker, web, and sandbox-supervisor (turbo filters in root `package.json`).

| Surface | URL |
|---------|-----|
| App (Vite) | http://127.0.0.1:**5173** |
| API | http://127.0.0.1:**3100** |

Desktop:

```bash
pnpm --filter @rakazo/desktop dev
```

### iPhone on the same Wi‑Fi (Mac LAN)

The mobile app can talk to a self-hosted API over **HTTP** on your local network. The API must listen on all interfaces, not only loopback.

```bash
# sets API_HOST=0.0.0.0 in .env, prints the URL, starts pnpm dev
bash scripts/dev-mobile-lan.sh
```

On the iPhone: open evOo → **Custom server** on sign-in → `http://<mac-lan-ip>:3100` (the script prints the IP). Allow **Local Network** when iOS asks.

Optional dev client: `pnpm --filter @rakazo/mobile start` and scan the QR code with Expo Go (you still set the custom server URL in the app).

## 5. Local models / Ollama seed

```bash
pnpm exec tsx scripts/seed-ollama.ts
```

Pi local provider: `packages/adapters/src/pi-local-provider.ts`.

## 6. Voice / Kokoro (not vendored)

Voice blobs are excluded from this repo. Run Kokoro-FastAPI yourself:

```bash
docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest
export KOKORO_BASE_URL=http://127.0.0.1:8880
```

Then connect **Kokoro** in Voice settings. See [kokoro-voice.md](./kokoro-voice.md).

## 7. Antigravity / future tools

| Tool | Path |
|------|------|
| self-update | `packages/core/src/self-update.ts` |
| local-stack | `apps/desktop/src/local-stack.ts` |
| pi-local-provider | `packages/adapters/src/pi-local-provider.ts` |
| seed-ollama | `scripts/seed-ollama.ts` |

## Tech debt: `@rakazo/*` package names

Display brand is **evOo**. Workspace package names remain `@rakazo/api`, `@rakazo/web`, `@rakazo/core`, … and some env/compose identifiers still use `RAKAZO_*` / DB name `rakazo`. Renaming would break imports and lockfile; track as follow-up.

## Source

Clean history cut from `cynarAI/evoo` commit `f00577b` on branch `antigravity-handoff/project-timeline` (Voice First + project timeline). This repo does **not** carry the old multi-remote history.