lumi-stack

One-command Proxmox LXC installer for Claude Code + Ruflo + Lumi AI assistant

Run a single command on your Proxmox VE node and get a fully configured Debian 13 container running a personal AI queen agent with web search, swarm orchestration, and an OpenAI-compatible HTTP API ready for Open WebUI.

---

Quick Start

On your Proxmox VE node, as root:

bash <(curl -fsSL https://raw.githubusercontent.com/morris1st/lumi-stack/main/proxmox/create-lxc.sh)

The interactive GUI walks you through container settings in three screens: Configure → Review → Install. Total time: ~5–10 minutes depending on network speed.

---

What Gets Installed

Component	Version	Purpose
OS	Debian 13 Trixie	LXC base system
Node.js	24.x	Runtime for Ruflo and lumi-proxy
mc, rlwrap, jq, …	latest	Developer tools
Claude Code	latest	AI engine (CLI)
Ruflo	latest	Swarm orchestration layer
Lumi	—	Queen agent with personality
lumi-chat	—	Terminal chat interface
lumi-proxy	—	OpenAI-compatible HTTP API on :3141
Config	/etc/lumi/lumid.conf	Central config file
Man pages	—	man lumi-chat, man lumi-proxy, man lumid.conf

---

Architecture

     Proxmox VE Node
    ┌─────────────────────────────────────────────────────┐
    │  proxmox/create-lxc.sh                              │
    │          │  (pct create + pct exec)                  │
    │          ▼                                           │
    │  ┌─────────────────────────────────────────────────┐│
    │  │          Debian 13 LXC Container                ││
    │  │                                                  ││
    │  │  ┌──────────┐   ┌──────────┐   ┌─────────────┐ ││
    │  │  │  Claude  │   │  Ruflo   │   │    Lumi     │ ││
    │  │  │   Code   │◄──│  Swarm   │◄──│    Queen    │ ││
    │  │  └──────────┘   └──────────┘   └─────────────┘ ││
    │  │        ▲                               ▲         ││
    │  │        │                               │         ││
    │  │  ┌─────┴───────────────────────────────┴──────┐ ││
    │  │  │        lumi-proxy  (port 3141)             │ ││
    │  │  │        OpenAI-compatible HTTP API          │ ││
    │  │  └────────────────────────────────────────────┘ ││
    │  └─────────────────────────────────────────────────┘│
    └─────────────────────────────────────────────────────┘
               ▲                            ▲
               │                            │
      Open WebUI (browser)         lumi-chat (terminal / SSH)

---

Chatting with Lumi

Terminal (inside the container)

# One-shot
lumi-chat "What is the fastest sorting algorithm for nearly-sorted data?"

# Pipe input
echo "Summarise this file" | lumi-chat

# Interactive REPL (with readline history)
lumi-chat

From the Proxmox host

pct exec <VMID> -- lumi-chat "Hello, Lumi!"

Open WebUI

1. Install Open WebUI anywhere on your network.
2. Go to Settings → Connections → OpenAI API.
3. Set the base URL to http://<CONTAINER_IP>:3141/v1 and any non-empty string as the API key.
4. Select the lumi model and start chatting.

See docs/open-webui.md for full details.

---

Configuration

All settings live in /etc/lumi/lumid.conf inside the container.

Key variables:

Variable	Default	Description
OPENROUTER_API_KEY	(set at install)	OpenRouter API key
ANTHROPIC_MODEL	openrouter/free	Top-level model
CLAUDE_CODE_SUBAGENT_MODEL	openrouter/free	Sub-agent model
LUMI_PROXY_PORT	3141	HTTP API port
LUMI_PERSONALITY_FILE	/home/lumi/lumi.md	Lumi's system prompt

After editing, restart services:

systemctl restart lumi-env lumi-proxy ruflo-lumi

See docs/configuration.md for the full variable reference and model examples.

---

Lumi's Personality

Lumi's system prompt lives at /home/lumi/lumi.md and is self-editable by Lumi. She defaults to:

• Searching the web before answering factual or procedural questions
• Spawning specialist swarm agents for large or parallel tasks
• Writing clearly in prose, switching language if you address her in one
• Updating her own personality file to record preferences

Edit lumi.md directly or ask Lumi to update it herself.

---

Services & Logs

# Status
systemctl status lumi-proxy ruflo-lumi lumi-env

# Live logs
journalctl -u lumi-proxy -f
journalctl -u ruflo-lumi -f

# Restart
systemctl restart lumi-proxy ruflo-lumi

# Reload config
systemctl restart lumi-env && systemctl restart lumi-proxy ruflo-lumi

---

Repository Structure

lumi-stack/
├── proxmox/
│   └── create-lxc.sh       # Proxmox GUI + LXC creator
├── container/
│   └── setup-lumi.sh       # Container installer (13 steps)
├── docs/
│   ├── configuration.md    # Full variable reference
│   ├── open-webui.md       # Open WebUI connection guide
│   └── troubleshooting.md  # Common issues & fixes
├── .github/
│   └── workflows/
│       └── ci.yml          # ShellCheck + markdownlint
├── README.md
├── CONTRIBUTING.md
├── LICENSE
└── .gitignore

---

Requirements

• Proxmox VE 7+ on the host node
• Internet access from the Proxmox node (to download the template and installer)
• Internet access from the container (to install packages and Claude Code)
• An OpenRouter API key (free tier works)

---

Troubleshooting

See docs/troubleshooting.md for solutions to common problems including:

• Empty response from lumi-chat
• claude binary not found
• Service not starting
• lumi-proxy unreachable from Open WebUI
• Claude OAuth prompt in headless LXC

---

License

MIT — see LICENSE.

---

Credits

• Anthropic Claude Code — the AI engine
• Ruflo / ruvnet — swarm orchestration
• Open WebUI — browser chat interface