From 214005353a52f363dd08e9387e94445096387dbc Mon Sep 17 00:00:00 2001
From: Taiga <taiga@hermes>
Date: Sun, 7 Jun 2026 17:18:49 +0000
Subject: [PATCH] [2026-06-07] taiga-vault: personal/projects/balda/setup.md

---
 personal/projects/balda/setup.md | 74 +++++++++++++++++++++++---------
 1 file changed, 53 insertions(+), 21 deletions(-)

diff --git a/personal/projects/balda/setup.md b/personal/projects/balda/setup.md
index 3f52cfa0..83ccf803 100644
--- a/personal/projects/balda/setup.md
+++ b/personal/projects/balda/setup.md
@@ -6,13 +6,26 @@
 
 | Item | Value |
 |------|-------|
-| Binary | `~/.local/bin/balda` |
-| Process | Native Mac process (PID changes on restart) |
+| Binary | `~/Developer/balda/balda` (built from source) |
+| Process | Managed by launchd (`com.normahq.balda`) |
 | 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) |
+| Provider | `deepseek` (openai type, model: `deepseek-chat`, via `https://api.deepseek.com/v1`) |
+
+Balda is managed by launchd. Full restart (reloads plist env vars):
+
+```bash
+launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.normahq.balda.plist
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.normahq.balda.plist
+```
+
+Quick restart (does NOT reload plist env vars — use bootout/bootstrap for env changes):
+
+```bash
+launchctl kickstart -k gui/$(id -u)/com.normahq.balda
+```
 
 ## Zulip Webhook
 
@@ -80,28 +93,44 @@ canceled when the parent is — so the goroutine lives past the HTTP handler ret
 
 **Solution:** Changed Balda's listen port from `8090` to `8091` in `config.yaml`.
 
-### Pending
+### Resolution
 
-- [ ] 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`
+Webhook bot URL updated in Zulip DB via `docker exec psql` on 2026-06-07:
+`http://host.docker.internal:8090/zulip/webhook` → `http://host.docker.internal:8091/zulip/webhook`
 
 ---
 
-## Starting / Restarting Balda
+## DeepSeek Provider via norma-local Fork
+
+Balda's `openai` provider type in norma hardcoded `api.openai.com`. To support
+DeepSeek (or any OpenAI-compatible API), the norma source was forked locally:
+
+- Fork path: `~/Developer/norma-local`
+- Patched files:
+  - `pkg/runtime/hostedagent/openai.go` — added `openAIBaseURL()` reading `OPENAI_BASE_URL` env var
+  - `pkg/runtime/agentfactory/agentfactory.go` — removed MCP restriction for `openai` type
+- Env var `OPENAI_BASE_URL=https://api.deepseek.com/v1` is set in the launchd plist
+- go.mod `replace` directive (`normahq/norma v0.0.6 → ../norma-local`) is local only
+  (not committed to the PR branch — needs a separate norma upstream PR or fork)
+
+To rebuild after patching norma:
 
 ```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
+cd ~/Developer/balda
+go build -o balda ./cmd/balda/
 ```
 
+---
+
+## CLAUDECODE Environment Bug (Fixed 2026-06-07)
+
+When launched from an Eagle terminal session, Balda inherited `CLAUDECODE=1`,
+which caused the Claude Code CLI to refuse to start (it detected a nested invocation).
+**Fix:** Use `launchctl bootout + bootstrap` to start Balda clean — launchd does
+not inherit parent shell env vars.
+
+---
+
 ## Config Snippet (key sections)
 
 ```yaml
@@ -111,14 +140,17 @@ balda:
 
 runtime:
   providers:
-    claude_code:
-      type: claude_code_acp
-      claude_code_acp:
-        model: claude-sonnet-4-6
+    deepseek:
+      type: openai
+      openai:
+        api_key: "<DeepSeek API key>"
+        model: deepseek-chat
 
 zulip:
   webhook:
     enabled: true
     listen: "0.0.0.0:8091"
     path: /zulip/webhook
+  allowed_owners:
+    - amartemyanov@duckduckgo.com
 ```