Documentation

Quick start (Linux)

You need an Ubuntu 24.04 environment with GCC 14 and about 13 GB of disk per build environment (the script refuses to start with less than 100 GB free). The reference clean build (Dev, CUDA off) measured 41 minutes on 5 of 16 cores; an unchanged re-run took about a minute.

git clone --recursive https://github.com/Keigyoku/lampway.git
cd lampway
scripts/lampway/build_linux.sh --check-deps
MIXAR_ENV=Prod scripts/lampway/build_linux.sh

python3 -m venv server/.venv
server/.venv/bin/pip install -r server/requirements-lock.txt
server/.venv/bin/pip install -e server/

scripts/lampway/lampway --env Prod --copy --provider mock path/to/scene.blend

--provider mock needs no model and no key; it is the smoke test. --plan prints every resolved setting without starting anything. The launcher starts the server on 127.0.0.1:8787, opens a copy of your file, and stops the server it started when the app exits. The build variables keep their upstream MIXAR_* names for now.

macOS and Windows: the build scripts are inherited from upstream and have not been run by this project.

Providers

# OpenRouter, hard session ceiling (default $3). The key is never an argument and never printed.
scripts/lampway/lampway --env Prod --copy --provider openrouter \
  --openrouter-key-file ~/.config/lampway/openrouter.env --budget 3 --image-backend openrouter scene.blend

# ChatGPT plan: open http://127.0.0.1:8787/app/chatgpt once, choose Continue with ChatGPT,
# approve in the browser, then LAMPWAY_PROVIDER=chatgpt_plan

# Anthropic API key
LAMPWAY_PROVIDER=anthropic ANTHROPIC_API_KEY=...

# Local or compatible server
LAMPWAY_PROVIDER=openai OPENAI_BASE_URL=http://127.0.0.1:11434/v1 LAMPWAY_OPENAI_MODEL=<model>

Swarm models, image models per purpose, spend policy per provider and the Higgsfield sign-in are in the Providers dialog. Local CLI adapters stay off unless you set LAMPWAY_LOCAL_CLI=1.

Connect AI apps (MCP)

1. Open Lampway and sign in to your Lampway server.
2. Open the profile menu, choose Connect AI Apps (MCP), and enable MCP.
3. Pick your app. Claude Code: claude mcp add --scope user lampway -- ~/.lampway/connector/lampway-mcp, or click Add. Codex: a [mcp_servers.lampway] table in ~/.codex/config.toml, or click Add. Others: merge the shown JSON into the app’s mcpServers.

The server is named lampway. An older mixar entry from a pre-Lampway build is replaced; the old launcher path forwards to the new one for one release. Only a loopback credential is written to disk, private to your user. Your own mouse or keyboard always takes control back, and spends on paid providers still wait for your click.

Spend safety

• Studio and Higgsfield jobs run get_cost first, then wait pending. Only a confirm from you starts them; the price must equal the one shown; the approval is one-shot and expires.
• No agent tool confirms. The client refuses the confirm while any script is running (the agent executor, a headless worker, the bridge).
• OpenRouter: every request carries a token cap, and a spend ledger refuses the next call past the session ceiling, before anything is sent.
• Per-provider spend policy (click: off, above a price, always; per-job and per-session caps) is set in the Providers dialog. Defaults: OpenRouter has a budget and no per-call click; Higgsfield and the studio always wait.

Configuration