# Balda — Setup & Config

_Последнее обновление: 2026-06-24_

## Хост

Mac (Eagle), **Colima** (arm64, 8 CPU, 24 GB RAM, 100 GB sparse disk). Контейнеры собираются из исходников в `~/Developer/balda/`.

**Важно:** `buildx_buildkit_arm64builder0_state` volume — основная причина зависаний Zulip при сборке. См. [[tech/docker-mac-disk-issues]].

## Компоненты

| Бот | Порт | Провайдер | Dockerfile |
|-----|------|-----------|------------|
| **Валера** (`balda-agent-valera-1`) | `:8091` | DeepSeek | `Dockerfile` (одинаковый) |
| **Клавдий** (`claudio-agent-claudio-1`) | `:8092` | Claude (через proxy :3457) | `Dockerfile.claudio` (тот же + arm64 target) |

## Расположение

| Item | Валера | Клавдий |
|------|--------|---------|
| Compose | `~/Docker/balda-agent/docker-compose.yaml` | `~/Docker/claudio-agent/docker-compose.yaml` |
| Config volume | `~/Docker/balda-agent/.config/balda/` | `~/Docker/claudio-agent/.config/balda/` |
| Env | `~/Docker/balda-agent/.env` | `~/Docker/claudio-agent/.env` |
| Dev repo (общий) | `~/Developer/balda/` | `~/Developer/balda/` |

**Важно:** оба бота собираются из одного репозитория `~/Developer/balda/` (normahq/balda fork). Разница — только в config.yaml (провайдер) и .env (Zulip credentials).

## Образ

- Собирается локально из `Dockerfile` (Go, multi-stage: golang:1.26 → alpine:3)
- Target: `linux/arm64` (статический Go бинарник)
- Image name: `balda-agent-valera:latest` / `claudio-agent-claudio:latest` (по имени compose проекта)
- Entrypoint: `/usr/local/bin/balda` (ELF arm64)
- Сеть: `balda_default` (bridge, внешняя, создаётся через docker network create)

## Запуск / рестарт

**Валера:**
```bash
cd ~/Docker/balda-agent
docker-compose restart              # без пересборки, без перечитывания .env
docker-compose up -d                # пересоздаёт контейнер с текущим .env
docker-compose build && docker-compose up -d  # после изменений в коде
```

**Клавдий:**
```bash
cd ~/Docker/claudio-agent
# те же команды
```

**После изменений кода** (в `~/Developer/balda/`): `build && up -d` в каждом compose.

## .env (общие переменные)

```env
OPENAI_BASE_URL=https://api.deepseek.com/v1   # обязательна для deepseek provider
# для claude provider не нужна
```

**Важно:** `docker-compose restart` не перечитывает `.env`. Только `docker-compose up -d`.

## Известные грабли

### 1. OPENAI_BASE_URL — обязательна для DeepSeek
Norma не читает `base_url` из config.yaml для `provider: deepseek`. Читает env `OPENAI_BASE_URL`.
Без неё запросы уходят на `api.openai.com` (401).

### 2. DOCKER_OPTS — пустая строка убивает старт
```env
DOCKER_OPTS={"max_tokens": 2048, "temperature": 0.7}
```
Не пустая строка! Иначе `strconv.ParseFloat: parsing ""` при старте.

### 3. exec format error на arm64
Симптом: контейнер в crash-цикле, логи повторяют `exec /usr/local/bin/balda: exec format error`.
Docker показывает `Up N hours` (накопленное время рестартов), но exec не работает.

**Причина:** контейнер создан с `Platform: linux/amd64` (старый Docker Desktop или первый run без platform). Образ arm64, контейнер amd64 — несовместимость.

**Фикс:** `docker-compose down; docker-compose up -d` — удаляет старый контейнер и создаёт новый с правильной платформой.

### 4. После перезапуска нужно @mention для создания сессии
Events API polling подхватывает сообщения только если есть активная сессия в теме.
После рестарта: написать `@Валера <текст>` (или `@Клавдий`).