# Balda — актуальный локальный запуск

Execution Broker, Telegram-одобрения и текущая приёмка: [[personal/projects/balda/execution-broker|Execution Broker — текущий локальный контур]].

_Проверено: 2026-10-09._

> Это основной runbook для текущей Balda на Mac. Старые документы про `balda-agent-valera-1`, Zulip и Kraken — исторические.

## Текущая схема

- Хост: Mac.
- Контейнер: `balda-mm-mac`.
- Канал: Mattermost.
- Провайдер: Codex ACP.
- Compose: `/Users/admin/Docker/balda-mm-mac/docker-compose.yml`.
- Конфиг: `/Users/admin/Docker/balda-mm-mac/config/config.yaml`.
- Состояние и managed plugins: `/Users/admin/Docker/balda-mm-mac/state`.
- Рабочие каталоги: `/Users/admin/Docker/balda-mm-mac/work`.

Каталоги `config`, `state` и `work` bind-mounted в контейнер. Домашний каталог контейнера хранится в Docker volume `balda_balda-home`.

## Что применять какой командой

| Изменение | Действие |
|---|---|
| Только содержимое `config/config.yaml` | `docker restart balda-mm-mac` |
| `.env`, environment, mounts или service definition в Compose | `docker-compose up -d balda` |
| Новый image/tag | `docker-compose pull && docker-compose up -d balda` |
| Изменение исходного кода | Собрать image, затем `docker-compose up -d balda` |
| Managed plugin | Использовать `/plugin install\|upgrade\|enable\|disable\|remove` |
| Plugin/skill для уже открытой беседы | `/reset` после активации изменения |

`docker restart` перечитывает bind-mounted `config.yaml`, потому что Balda читает его при старте процесса. Он не перечитывает `.env` и не применяет изменения Compose.

Принудительное `--force-recreate` для изменения только `config.yaml` не требуется.

## Plugins и skills

Managed plugin revisions в `state` неизменяемые и проверяются по digest. Их нельзя редактировать вручную в папке. Изменения устанавливаются через команды `/plugin`.

Каталог плагинов обновляется в работающем процессе после install/upgrade/enable/disable/remove. Уже созданная сессия закреплена за старым snapshot, поэтому для неё нужен `/reset`.

Файлы standalone skills редактировать можно, но существующая сессия также увидит новый snapshot только после `/reset`.

## Codex ACP

Актуальный reasoning effort: `medium`.

Codex авторизация хранится в home-volume контейнера. Для headless-входа:

```bash
cd /Users/admin/Docker/balda-mm-mac
docker-compose run --rm --entrypoint codex balda login --device-auth
```

## Obsidian MCP

Codex ACP поддерживает `stdio` и Streamable HTTP. SSE-конфигурация не поддерживается.

```yaml
mcp_servers:
  obsidian:
    type: http
    url: http://host.docker.internal:3101/mcp
    name: obsidian
```

После изменения только этого блока:

```bash
docker restart balda-mm-mac
```

## Проверка

```bash
docker ps --filter name=balda-mm-mac
docker logs --tail 120 balda-mm-mac
```

В логах должны быть успешная инициализация Codex ACP, готовность provider и подключение Mattermost WebSocket.