README.md

← lucebox-hub

Lucebox Harness

Client launchers and regression tests for Lucebox server compatibility.
Run Lucebox from Claude Code, Codex, OpenCode, Hermes, OMP, Pi, OpenClaw, or Open WebUI.
RTX 3090 / 24 GB defaults are included for each client.

---

Use this folder to launch Lucebox through a real client, or to test a server change against the HTTP protocols those clients use. Paths and server settings can be overridden with environment variables.

Run a client

Each script starts Lucebox, runs one real client, saves logs, then stops the server.

cd lucebox-hub

harness/clients/run_codex.sh
harness/clients/run_claude_code.sh
harness/clients/run_opencode.sh
harness/clients/run_omp.sh

The launchers default to the current repo, install/use client packages under .harness-work/, and write logs under .harness-work/runs/. Override REPO_DIR, CLIENT_WORK_DIR, or RUN_DIR if you want shared paths. If a client CLI is missing, the launcher installs it automatically. Set AUTO_INSTALL_CLIENTS=0 to require a preinstalled binary instead.

Common overrides:

MAX_CTX=32768 BUDGET=22 VERIFY_MODE=ddtree harness/clients/run_codex.sh
PROMPT_FILE=harness/clients/prompts/repo_inspection.txt harness/clients/run_hermes.sh
CLIENT=opencode harness/clients/run_backend_pair.sh

Use the native C++ server:

harness/clients/run_codex.sh

The native server binary defaults to server/build/luce_server. Override the paths and profile:

LUCE_SERVER_BIN=server/build/luce_server \
TARGET=server/models/Qwen3.6-27B-Q4_K_M.gguf \
DRAFT=server/models/draft/dflash-draft-3.6-q4_k_m.gguf \
MODEL_ID=luce-dflash \
MAX_CTX=32768 MAX_TOKENS=512 \
BUDGET=22 VERIFY_MODE=ddtree FA_WINDOW=2048 \
harness/clients/run_codex.sh

To test an already-running native server:

server/build/luce_server server/models/Qwen3.6-27B-Q4_K_M.gguf \
  --draft server/models/draft/dflash-draft-3.6-q4_k_m.gguf \
  --host 127.0.0.1 --port 18080 \
  --max-ctx 32768 --max-tokens 512 \
  --fa-window 2048 \
  --ddtree --ddtree-budget 22 \
  --model-name luce-dflash

python3 harness/client_test_runner.py probe \
  --url http://127.0.0.1:18080 \
  --clients all

The per-client defaults live in clients/README.md. They are not all the same: a tool-heavy agent prompt and a chat/proxy prompt need different context limits on a 24 GB card.

Test a server change

If you already have luce_server running, use probe:

python3 harness/client_test_runner.py probe \
  --url http://127.0.0.1:8000 \
  --clients claude_code,codex,opencode,omp,openwebui,pi \
  --json-out /tmp/lucebox_harness_probe.json

Add --install-packages when you also want the runner to install/smoke the client packages. Without it, the HTTP protocol probes still run.

To preinstall real-client CLIs yourself:

python3 harness/client_test_runner.py install --clients codex,hermes,omp,openwebui

For a GPU sweep, let the runner start Lucebox for each profile:

python3 harness/client_test_runner.py sweep \
  --target server/models/Qwen3.6-27B-Q4_K_M.gguf \
  --draft server/models/draft \
  --bin server/build/test_dflash \
  --profiles rtx3090_luce_safe,rtx3090_luce_long \
  --clients all \
  --json-out /tmp/lucebox_harness_sweep.json

Use --isolate-clients when you want each client tested against a fresh server.

Compare with llama.cpp

For client-level speed checks, run the same harness once against llama.cpp and once against Lucebox:

CLIENT=opencode PROMPT_FILE=harness/clients/prompts/repo_inspection.txt \
  harness/clients/run_backend_pair.sh

This keeps the client prompt, tools, and request shape the same for both backends.

Files

• client_test_runner.py: package smoke tests, protocol probes, and server sweeps
• clients/: real client launchers
• clients/prompts/: short prompts used by the launchers
• benchmarks/: direct generation benchmark against OpenAI-compatible servers
• qualification/: reproducible, hardware-specific performance qualification