125 lines
3.3 KiB
Markdown
125 lines
3.3 KiB
Markdown
# Balda Setup & Status
|
|
|
|
> Last updated: 2026-06-07
|
|
|
|
## Runtime
|
|
|
|
| Item | Value |
|
|
|------|-------|
|
|
| Binary | `~/.local/bin/balda` |
|
|
| Process | Native Mac process (PID changes on restart) |
|
|
| Log | `/private/tmp/balda.log` |
|
|
| Config | `~/Developer/balda/.config/balda/config.yaml` |
|
|
| State dir | `~/Developer/balda/.config/balda/` |
|
|
| Sessions | SQLite persistence |
|
|
| Provider | `claude_code_acp` (Claude Code ACP, model: claude-sonnet-4-6) |
|
|
|
|
## Zulip Webhook
|
|
|
|
| Item | Value |
|
|
|------|-------|
|
|
| Status | ENABLED |
|
|
| Listen address | `0.0.0.0:8091` |
|
|
| Path | `/zulip/webhook` |
|
|
| Webhook bot URL | `http://host.docker.internal:8091/zulip/webhook` |
|
|
|
|
Port was **changed from 8090 → 8091** on 2026-06-07 (see Port Conflict below).
|
|
|
|
## Architecture
|
|
|
|
Balda uses the **outgoing webhook** mechanism — Zulip pushes events to Balda's
|
|
HTTP endpoint. This differs from Eagle/Kit which use polling.
|
|
|
|
- Zulip runs in Docker (container: `zulip-zulip-1`), exposed on `127.0.0.1:8000`
|
|
- Balda runs natively on Mac (not in Docker)
|
|
- Colima maps `host.docker.internal:PORT → 127.0.0.1:PORT` on the Mac host,
|
|
so the bot URL uses `host.docker.internal` to reach Balda from inside Docker
|
|
|
|
## Soul / Prompt
|
|
|
|
The `global_instruction` field in `config.yaml` defines Balda's persona (Валера).
|
|
The canonical source is `soul.md` in this folder — sync manually to config after edits,
|
|
then restart Balda.
|
|
|
|
Provider-level `system_instructions` are documented in `workspace-context.md`.
|
|
|
|
---
|
|
|
|
## Bug Fixed 2026-06-07 — Context Canceled on First DB Operation
|
|
|
|
**File:** `zulip_handler.go`, line 236
|
|
|
|
**Root cause:** The message-processing goroutine was launched with the HTTP
|
|
request context:
|
|
|
|
```go
|
|
// Before (broken)
|
|
go h.processMessage(r.Context(), payload)
|
|
```
|
|
|
|
When the handler returns HTTP 200, Go cancels `r.Context()`. The goroutine then
|
|
hits its first database operation and fails with `context canceled`.
|
|
|
|
**Fix:**
|
|
|
|
```go
|
|
// After (fixed)
|
|
go h.processMessage(context.WithoutCancel(r.Context()), payload)
|
|
```
|
|
|
|
`context.WithoutCancel` creates a copy of the parent context that is never
|
|
canceled when the parent is — so the goroutine lives past the HTTP handler return.
|
|
|
|
---
|
|
|
|
## Port Conflict 2026-06-07 — Moved 8090 → 8091
|
|
|
|
**Root cause:** Colima (Docker runtime) maps `host.docker.internal:PORT →
|
|
127.0.0.1:PORT` on the Mac host. `openclaw/claude-proxy` was occupying
|
|
`127.0.0.1:8090`, intercepting Balda's webhook traffic before it reached Balda.
|
|
|
|
**Solution:** Changed Balda's listen port from `8090` to `8091` in `config.yaml`.
|
|
|
|
### Pending
|
|
|
|
- [ ] Update Zulip webhook bot URL from `8090` to `8091`
|
|
- In Zulip admin: Settings → Bots → edit the outgoing webhook bot
|
|
- Or via `docker exec zulip-zulip-1 python manage.py ...`
|
|
- New URL: `http://host.docker.internal:8091/zulip/webhook`
|
|
|
|
---
|
|
|
|
## Starting / Restarting Balda
|
|
|
|
```bash
|
|
# View logs
|
|
tail -f /private/tmp/balda.log
|
|
|
|
# Start (runs in background, logs to /private/tmp/balda.log)
|
|
~/.local/bin/balda serve >> /private/tmp/balda.log 2>&1 &
|
|
|
|
# Check if running
|
|
pgrep -l balda
|
|
```
|
|
|
|
## Config Snippet (key sections)
|
|
|
|
```yaml
|
|
balda:
|
|
global_instruction: |
|
|
<contents of soul.md>
|
|
|
|
runtime:
|
|
providers:
|
|
claude_code:
|
|
type: claude_code_acp
|
|
claude_code_acp:
|
|
model: claude-sonnet-4-6
|
|
|
|
zulip:
|
|
webhook:
|
|
enabled: true
|
|
listen: "0.0.0.0:8091"
|
|
path: /zulip/webhook
|
|
```
|