im_wower
·
2026-03-29
environment.md
1# runtime environment
2
3当前只保留 `mini` 单节点变量，默认口径如下：
4
5- canonical local API: `http://100.71.210.78:4317`
6- canonical local Firefox WS: `ws://100.71.210.78:4317/ws/firefox`
7- codexd local API: `http://127.0.0.1:4319`
8- codexd event stream: `ws://127.0.0.1:4319/v1/codexd/events`
9- canonical public host: `https://conductor.makefile.so`
10- local status view: `http://100.71.210.78:4318`
11- `status-api` 默认真相源：`BAA_CONDUCTOR_LOCAL_API` -> `http://100.71.210.78:4317/v1/system/state`
12- `conductor` upstream/public API base 的 canonical 变量名是 `BAA_CONDUCTOR_PUBLIC_API_BASE`
13- legacy 变量名 `BAA_CONTROL_API_BASE` 只剩两个保留点：`conductor` 把它当兼容别名，`status-api` 只在手工兼容场景下回退读取
14
15## 共享变量
16
17- `BAA_SHARED_TOKEN`
18- `BAA_RUNS_DIR`
19- `BAA_WORKTREES_DIR`
20- `BAA_LOGS_DIR`
21- `BAA_TMP_DIR`
22- `BAA_STATE_DIR`
23
24说明：
25
26- `codexd` 独立安装时不要求 `BAA_SHARED_TOKEN`
27
28## conductor public API 变量
29
30- `BAA_CONDUCTOR_PUBLIC_API_BASE`
31- `BAA_CONTROL_API_BASE`
32
33说明：
34
35- `BAA_CONDUCTOR_PUBLIC_API_BASE` 是 canonical 配置名，`BAA_CONTROL_API_BASE` 是 legacy 兼容别名
36- 如果两个 env 同时存在，`BAA_CONDUCTOR_PUBLIC_API_BASE` 优先
37- launchd 安装脚本会把这两个名字都写给 `conductor` 安装副本，避免新旧副本/脚本混跑时失配
38- `status-api` 现在会优先读取 `BAA_CONDUCTOR_LOCAL_API`，只有手工启动或旧配置缺少该值时才回退到 `BAA_CONTROL_API_BASE`
39- mini 默认兼容值仍是 `https://conductor.makefile.so`
40
41## 可选 D1 同步变量
42
43- `D1_ACCOUNT_ID`
44- `D1_DATABASE_ID`
45- `CLOUDFLARE_API_TOKEN`
46
47说明：
48
49- 这组三元组只对 `conductor` 生效，用于启用 artifact D1 sync worker
50- 三个值必须同时存在；只配其中一部分时，launchd 安装脚本会直接报错
51- `install-launchd.sh` / `install-mini.sh` 会优先读取当前 shell env，也支持从 `~/.config/baa-conductor/runtime-secrets.env` 之类的 env 文件读取
52- 当前正式运行面只把这组三元组写给 `conductor` 安装副本，不会写给 `codexd` / `status-api`
53
54## codexd 变量
55
56`apps/codexd` 当前识别这些变量：
57
58- `BAA_CODEXD_REPO_ROOT`
59- `BAA_CODEXD_LOCAL_API_BASE`
60- `BAA_CODEXD_EVENT_STREAM_PATH`
61- `BAA_CODEXD_MODE`
62- `BAA_CODEXD_LOGS_DIR`
63- `BAA_CODEXD_STATE_DIR`
64- `BAA_CODEXD_SERVER_ENDPOINT`
65- `BAA_CODEXD_SERVER_STRATEGY`
66- `BAA_CODEXD_SERVER_COMMAND`
67- `BAA_CODEXD_SERVER_ARGS`
68- `BAA_CODEXD_SERVER_CWD`
69- `BAA_CODEXD_EVENT_CACHE_SIZE`
70- `BAA_CODEXD_SMOKE_LIFETIME_MS`
71- `BAA_CODEXD_VERSION`
72
73正式 launchd 运行面默认写入：
74
75```text
76BAA_CODEXD_REPO_ROOT=/Users/george/code/baa-conductor
77BAA_CODEXD_LOCAL_API_BASE=http://127.0.0.1:4319
78BAA_CODEXD_EVENT_STREAM_PATH=/v1/codexd/events
79BAA_CODEXD_MODE=app-server
80BAA_CODEXD_SERVER_STRATEGY=spawn
81BAA_CODEXD_SERVER_COMMAND=codex
82BAA_CODEXD_SERVER_ARGS=app-server
83BAA_CODEXD_SERVER_CWD=/Users/george/code/baa-conductor
84BAA_CODEXD_SERVER_ENDPOINT=stdio://codex-app-server
85BAA_CODEXD_LOGS_DIR=/Users/george/code/baa-conductor/logs/codexd
86BAA_CODEXD_STATE_DIR=/Users/george/code/baa-conductor/state/codexd
87```
88
89说明：
90
91- 正式运行面只支持 `app-server`
92- 正式 API 只保留 `/healthz`、`/describe`、`/v1/codexd/status`、`/v1/codexd/sessions`、`/v1/codexd/sessions/:session_id`、`/v1/codexd/turn`、`/v1/codexd/events`
93- 正式运行面只保留这条 `app-server` 会话链路所需变量
94- `BAA_CODEXD_LOCAL_API_BASE` 必须保持 loopback host；当前默认是 `127.0.0.1:4319`
95
96## 节点变量
97
98```text
99BAA_CONDUCTOR_HOST=mini
100BAA_CONDUCTOR_ROLE=primary
101BAA_NODE_ID=mini-main
102BAA_CONDUCTOR_LOCAL_API=http://100.71.210.78:4317
103BAA_CONDUCTOR_LOCAL_API_ALLOWED_HOSTS=100.71.210.78
104BAA_CODEXD_LOCAL_API_BASE=http://127.0.0.1:4319
105BAA_STATUS_API_HOST=100.71.210.78
106BAA_CONDUCTOR_PUBLIC_API_BASE=https://conductor.makefile.so
107BAA_CONTROL_API_BASE=https://conductor.makefile.so
108```
109
110最后两项现在都只写给 `conductor` 安装副本；`status-api` 的默认真相源仍然是 `BAA_CONDUCTOR_LOCAL_API=http://100.71.210.78:4317`，默认 launchd 不再额外携带这些 conductor public-api base 变量。
111
112说明：
113
114- `BAA_CODEXD_LOCAL_API_BASE` 不只是 `codexd` 自己使用，`conductor` 也通过它代理 `/v1/codex*`
115- 这个值必须保持 loopback 地址；当前正式值是 `http://127.0.0.1:4319`
116- 如果 `conductor` 进程缺这个变量，`/v1/codex` 会返回 `503 codexd_not_configured`
117
118Firefox WS 派生规则：
119
120- 不新增 `BAA_CONDUCTOR_FIREFOX_WS` 之类单独变量
121- 运行时直接从 `BAA_CONDUCTOR_LOCAL_API` 派生
122- 公式固定为 `${BAA_CONDUCTOR_LOCAL_API}` 把 scheme 从 `http` 换成 `ws`，再把 path 设为 `/ws/firefox`
123
124例如：
125
126- `http://100.71.210.78:4317` -> `ws://100.71.210.78:4317/ws/firefox`
127- `http://127.0.0.1:4317` -> `ws://127.0.0.1:4317/ws/firefox`
128
129## 最小例子
130
131```bash
132./scripts/runtime/install-launchd.sh \
133 --repo-dir /Users/george/code/baa-conductor \
134 --node mini \
135 --service conductor \
136 --service codexd \
137 --shared-token-file /Users/george/.config/baa-conductor/shared-token.txt \
138 --d1-secrets-env /Users/george/.config/baa-conductor/runtime-secrets.env \
139 --local-api-base http://100.71.210.78:4317 \
140 --local-api-allowed-hosts 100.71.210.78 \
141 --codexd-local-api-base http://127.0.0.1:4319
142```
143
144默认 mini 安装不需要显式传 `--public-api-base`；只有 `conductor` 的 upstream/public API base 不是 `https://conductor.makefile.so` 时才需要覆盖。`--control-api-base` 仍可作为 legacy 兼容别名使用；如果同一轮 CLI 同时给出新旧参数名，`--public-api-base` 优先。脚本现在也只会把这些变量写给 `conductor` 安装副本；`status-api` 默认仍然优先读取 `--local-api-base` 对应的 conductor 主接口。
145
146如果你希望 launchd 安装副本稳定带上 D1 同步配置，可以在 `runtime-secrets.env` 里补这三行：
147
148```text
149D1_ACCOUNT_ID=3cb181c015e004e4d6f81891c0d66fec
150D1_DATABASE_ID=<cloudflare-d1-database-id>
151CLOUDFLARE_API_TOKEN=<api-token>
152```
153
154如果要安装可选状态观察面，再单独执行：
155
156```bash
157./scripts/runtime/install-launchd.sh \
158 --repo-dir /Users/george/code/baa-conductor \
159 --node mini \
160 --service status-api \
161 --status-api-host 100.71.210.78
162```