Devbox Li development (engine and agents)¶

Short setup guide for human developers and Cursor agents working on the Li monorepo from a dedicated Linux dev machine (hostname engine, Debian 12).

See also: Getting started — tools (generic macOS/Linux), httpd M1 baseline, Cursor devbox host notes (sleep/LUKS/RAM on the host).

What you need¶

Sibling repos (clone next to each other):

~/Documents/Cursor/li-langverse/
  lic/                 # compiler + li-httpd runtime
  li-cursor-agents/    # Cursor SDK agents
  benchmarks/          # agent briefing / preflight

One-time machine setup¶

1. System packages (sudo once)¶

cd ~/Documents/Cursor/li-langverse/lic
chmod +x scripts/setup-li-devbox.sh
sudo bash scripts/setup-li-devbox.sh --full

--full installs apt packages, user Node under ~/.local/node, writes ~/.config/environment.d/99-li-dev.conf, and runs ./scripts/build.sh.

Without sudo, run only the user layer (Node + env file):

bash scripts/setup-li-devbox.sh --user

2. New shell¶

Log out/in or source ~/.config/environment.d/99-li-dev.conf so PATH, LLVM_DIR, CC, and CXX are set.

Verify:

which clang-22 node npm
echo "$LLVM_DIR"
cd ~/Documents/Cursor/li-langverse/lic
./build/compiler/lic/lic --version

3. Cursor / httpd agent env¶

Create ~/Documents/Cursor/.env (never commit) with:

CURSOR_API_KEY=...
GH_TOKEN=...          # or GITHUB_TOKEN
LI_CONTROL_PLANE_STORE=disk
LI_SDK_TERMINAL_STREAM=1
LI_AGENT_MINIMAL_PROMPT=1
LI_CURSOR_AGENTS_ROOT=~/Documents/Cursor/li-langverse/li-cursor-agents
BENCHMARKS_ROOT=~/Documents/Cursor/li-langverse/benchmarks
LIC_ROOT=~/Documents/Cursor/li-langverse/lic

Build agents once:

export PATH="$HOME/.local/node/bin:$PATH"
cd ~/Documents/Cursor/li-langverse/li-cursor-agents
git checkout feat/goal-directed-sdk-loop   # or main after merge
npm ci && npm run build

Daily commands¶

Build compiler¶

cd ~/Documents/Cursor/li-langverse/lic
./scripts/build.sh
export LIC="$(./scripts/resolve-lic.sh)"
"$LIC" build --allow-open-vc li-tests/routing/match_routes.li -o /tmp/match_routes

httpd M1 gates¶

Full (needs lic + optional build/li-httpd):

./scripts/httpd-plan-gates.sh

Python-only (no lic binary yet — CI smoke on constrained hosts):

HTTPD_GATES_SKIP_LIC_BUILD=1 HTTPD_RUN_BEARER_TEST=0 ./scripts/httpd-plan-gates.sh

Build the C httpd binary:

./scripts/build-li-httpd.sh
./scripts/test-auth-bearer.sh

Autonomous httpd plan loop¶

Branches:

• Implementation: cursor/httpd-plan-loop-54aa → PR #173
• Loop script: cursor/httpd-plan-loop-goal-directed → PR #172
• SDK: li-cursor-agents feat/goal-directed-sdk-loop → PR #9

source ~/Documents/Cursor/.env
export PATH="$HOME/.local/node/bin:$PATH"
cd ~/Documents/Cursor/li-langverse/lic
git checkout cursor/httpd-plan-loop-54aa

./scripts/httpd-plan-loop.py --dry-run    # next todo + prompt
./scripts/httpd-plan-loop.py --once       # one code_implementer run
./scripts/httpd-plan-loop.py --max 15     # batch

The loop uses code_implementer with --goal-file (not httpd_implementer). It prefers M1 plan todos over w0/w1 language blockers unless LI_HTTPD_PLAN_INCLUDE_BLOCKERS=1.

Mark a todo done in loop state without running the agent:

./scripts/httpd-plan-loop.py --mark-done m1-routing-tests

Agent rules (httpd)¶

1. Work on cursor/httpd-plan-loop-54aa; open/update PR #173 — do not self-merge.
2. Run ./scripts/httpd-plan-gates.sh before claiming done (or document HTTPD_GATES_SKIP_LIC_BUILD=1 if only Python changed).
3. Update plan YAML todo status in docs/superpowers/plans/2026-05-16-li-httpd-plan.md when a slice is truly complete.
4. Release notes under docs/release-notes/ + CHANGELOG.md.
5. Do not merge stale httpd PRs (#87, #84, #130) wholesale.

Troubleshooting¶

Host notes (engine)¶

• RAM: ~64 GiB physical; swap ~1 GiB — see Cursor memory cap script in repo Documents/Cursor/scripts/.
• SSH: laptop → engine (LAPTOP-SSH-SETUP.md).
• LUKS: unattended reboot may need TPM unlock (setup-devbox-always-on.sh).