Fast, scriptable command-line interface for Loxone Miniserver. Single binary. No runtime. No cloud. Works in scripts, cron jobs, and AI agent pipelines.
The Loxone app is great for everyday use — but it offers no API or scripting support for automation, CI/CD pipelines, or headless environments.
lox gives you a proper CLI so you can:
- Script your home — bash, Python, cron, whatever
- Connect AI agents — Claude, GPT, or any LLM tool can control your home via shell commands
- Chain commands —
lox if "Temperatur" gt 25 && lox blind "Südseite" pos 80 - Integrate with anything — exit codes, JSON output, stdin/stdout
# Turn off all lights when leaving
lox off "Licht Wohnzimmer Zentral" && lox blind "Südseite" full-up
# AI agent can call these:
lox ls --type LightControllerV2 -o json | jq '.[].name'
lox light mood "Wohnzimmer" off
lox status -o json | jq '.plc_running'
# Disambiguate sensors with the same name using --room or bracket syntax
lox get "Temperatur" --room "Schlafzimmer"
lox get "Temperatur [OG Kinderzimmer Bastian]"
# Quick energy overview
lox status --energy
# Conditionally close blinds
lox if "Temperatur Außen" gt 28 && lox blind "Beschattung Süd" pos 70This CLI was designed for AI agent integration. Every command:
- Exits
0on success, non-zero on error - Has
-o jsonflag for structured output - Uses fuzzy name matching — agents don't need UUIDs
- Supports
--roomflag and[Room]bracket syntax to resolve ambiguous names - Returns readable errors with suggestions
--dry-runvalidates without executing — preview what would happen--trace-idcorrelates agent actions across logs--non-interactivefails instead of prompting (implied by-o json)lox schemalets agents discover available commands programmatically- Errors return structured JSON envelopes with categorized error codes
Example: give an LLM a shell tool
{
"name": "lox",
"description": "Control Loxone smart home. Use -o json for structured output.",
"parameters": {
"command": { "type": "string", "description": "e.g. 'on Wohnzimmer', 'blind Südseite pos 50', 'status --energy'" }
}
}The agent calls lox <command> as a shell tool and reads stdout. That's it.
An agent can discover your home (lox ls -o json), read sensor values, control devices, and check conditions — all without any custom integration layer.
MCP server (Claude Desktop, ChatGPT, Cursor, …): clients that only speak the
Model Context Protocol can launch lox mcp serve directly.
Built on the official Rust MCP SDK, it speaks MCP 2026-07-28 and every older revision, and exposes
schema-typed tools (rooms, controls, live state, switches, blinds, lights, climate, scenes) over stdio.
Doors, gates, the alarm and any control you list under confirm: ask you to confirm in the MCP client before anything is sent.
lox mcp config # print a ready-to-paste client config
claude mcp add loxone -- lox mcp serve # Claude Code
lox mcp tools # list the tools a client will seeSee the AI agent guide for the tool list and safety model.
Agent-friendly workflow:
lox schema -o json # discover available commands
lox ls -o json # discover controls
lox --dry-run on "Licht" -o json # preview before executing
lox --trace-id "run-42" on "Licht" # execute with tracing
lox health --problems -o json # check device healthWindows (PowerShell):
irm https://raw.githubusercontent.com/discostu105/lox/main/install.ps1 | iexThis downloads the latest release to %LOCALAPPDATA%\lox and adds it to your PATH.
Or install manually: download lox-windows-x86_64.exe from the latest release, rename to lox.exe, and place it somewhere on your PATH.
Homebrew (macOS/Linux):
brew tap discostu105/lox https://github.com/discostu105/lox
brew install discostu105/lox/loxBuild from source (all platforms):
git clone https://github.com/discostu105/lox
cd lox
cargo build --releaseThe binary is at target/release/lox (or lox.exe on Windows). Copy it somewhere on your PATH.
Requirements (source): Rust 1.91+. No OpenSSL. No runtime dependencies. Works on Windows, macOS, and Linux.
lox setup set --host https://192.168.1.100 --user USER --pass PASS
# With serial for correct TLS hostname (avoids cert warnings)
lox setup set --host https://192.168.1.100 --user USER --pass PASS --serial YOUR_SERIALConfig location:
- macOS/Linux:
~/.lox/config.yaml - Windows:
C:\Users\<YOU>\.lox\config.yaml
Manage multiple connections with named contexts:
lox ctx add home --host https://192.168.1.100 --user admin --pass secret
lox ctx add office --host https://10.0.0.50 --user admin --pass secret
lox ctx use home # switch active context
lox --ctx office status # one-off command against a different contextAdd short names for frequently-used controls in your config.yaml:
host: https://192.168.1.100
user: admin
pass: secret
aliases:
wz: "1d8af56e-036e-e9ad-ffffed57184a04d2" # Lichtsteuerung Wohnzimmer
kueche: "20236c09-0055-6e94-ffffed57184a04d2" # Licht Küche InselThen use short names directly: lox on wz, lox off kueche
Homebrew installs completions automatically — no extra steps needed.
Manual install (one command, auto-detects your shell):
lox completions --installOr generate to stdout for custom setups: lox completions bash|zsh|fish|powershell
PowerShell — add this to your $PROFILE:
lox completions powershell | Out-String | Invoke-ExpressionQuick overview — see COMMANDS.md for the full reference with all options.
lox ls # List all controls
lox ls -t Jalousie -r "EG" # Filter by type/room/category
lox get "Temperatur [Schlafzimmer]" # Read a control's state
lox on "Licht Wohnzimmer" # Turn on
lox off "Licht Wohnzimmer" # Turn off
lox blind "Beschattung Süd" pos 50 # Blind to 50%
lox light mood "Licht" plus # Next light mood
lox light moods "Licht" # List available moods
lox thermostat "Heizung" temp 22.5 # Set temperature
lox alarm "Alarmanlage" arm # Arm alarm
lox tui # Live terminal UI — btop for your house
lox tui --demo # …try it without a Miniserver
lox stream --room "Kitchen" -o json # Real-time WebSocket state stream
lox otel serve --endpoint http://.. # Push metrics, logs & traces via OTLP
lox if "Temperatur" gt 25 && echo hot # Conditional logic
lox status --energy # Energy dashboard
lox config download --extract # Download & extract Loxone Config
lox config diff old.Loxone new.Loxone # Compare two configs
lox config init ~/loxone-config # Init git repo for config versioning
lox config pull # Download, diff & git-commit config
lox config log # Show config change history
lox config restore abc123 --force # Restore config from git history
lox run abend # Run a scene
lox health --problems # Device health (battery, signal, offline)
lox schema blind # Command schema for AI agent discovery
lox mcp serve # MCP server for Claude Desktop, ChatGPT, Cursor, …
lox completions bash # Generate shell completionslox tui is a full-screen, keyboard-first live view of your installation — btop for your house.
Recorded from lox tui --demo with scripts/demo-video — reproducible, no Miniserver needed.
What's in it:
- Home — room cards, what needs attention (open windows, low batteries, offline devices), pinned controls, a live feed
- Rooms — every control with its live value;
␣toggles,+/-dim,=sets a value,mpicks a mood,ashows all actions - Events — every state change as it happens, filterable, with "what happened just before" correlation
- Energy — animated PV / home / grid / battery flow, meters, today's curve
- System — CPU, heap, devices, CAN bus & LAN, the Miniserver log, and config history with semantic diffs
- Sites — all your Miniservers at a glance; switch live
- Wiring (
w) — the config program around a control, with live values on the wires: why is this light on? - History (
c) — any control's statistics over 6 h to a year, with period compare, a cursor and extra series
lox tui # connect to the current context
lox tui --demo # a synthetic demo house, no Miniserver needed
lox tui --read-only # wall display: look, don't touch: opens a fuzzy palette for rooms, controls, scenes and any lox command; ? shows the keys; y copies the
equivalent lox command for scripting. Doors, alarms and gates ask for confirmation, reboot and update ask you to type
the context name. See COMMANDS.md for all flags and keys.
The Wiring view and the semantic config diffs are built on lxir, which parses
.Loxone configs into program blocks and wires.
YAML files in ~/.lox/scenes/:
# ~/.lox/scenes/abend.yaml
name: Abend
steps:
- control: "Lichtsteuerung Wohnzimmer"
cmd: on
- control: "Beschattung Südseite"
cmd: "pos 70"
- control: "LED Küche"
cmd: off
delay_ms: 500Structure cache at ~/.lox/cache/structure.json (24h TTL):
| Operation | Cold | Warm |
|---|---|---|
lox on "Licht" |
~1.2s | ~80ms |
lox ls |
~1.2s | ~80ms |
lox ls --values |
~1.2s + N×req | slower (one HTTP request per control) |
lox status |
~120ms | ~120ms |
| Type | Commands |
|---|---|
LightControllerV2 |
on, off, mood plus/minus/off/<id> |
Jalousie / CentralJalousie |
up, down, stop, pos <0-100>, shade, full-up, full-down |
Switch |
on, off, pulse |
Dimmer |
dimmer <name> <0-100> |
Gate / CentralGate |
gate <name> open/close/stop |
ColorPickerV2 |
color <name> #RRGGBB or color <name> "hsv(h,s,v)" |
IRoomControllerV2 |
thermostat <name> --temp/--mode/--override |
Alarm |
alarm <name> arm/disarm/quit |
InfoOnlyAnalog / Meter |
get (read-only) |
| Any | send <uuid> <raw-command>, lock, unlock |
Track Miniserver configuration changes in a git repository — automated backups with meaningful commit messages:
# One-time setup
lox config init ~/loxone-config
# Pull current config, diff against previous, commit with semantic message
lox config pull
# View history
lox config log
# Restore a previous version
lox config restore abc123 --forceEach pull downloads the config via FTP, decompresses the proprietary LoxCC format to XML, generates a semantic diff (controls/rooms/users added/removed/renamed), and commits with a meaningful message like:
[504F94AABBCC] Config backup 2026-03-08 18:22:56 (v42)
+ Added control: "Garage Light" (Switch)
~ Light: "Licht EG" -> "Licht Erdgeschoss"
- Removed user: "guest"
Cron-friendly: lox config pull --quiet for automated nightly backups.
Multi-Miniserver: each Miniserver gets its own subdirectory (by serial number).
Safe restore: uploads the original backup ZIP from git history (no risky recompression).
~/.lox/
config.yaml # Host, credentials, serial, aliases
cache/
structure.json # LoxApp3.json (24h TTL, ~150KB)
token.json # Token auth (optional)
scenes/*.yaml # Your scenes
Single static Rust binary ~4MB. TLS via rustls (no OpenSSL). Self-signed certs accepted. Works on Windows, macOS, and Linux.
- lxir — Loxone config-as-code: a text language compiled to
.Loxoneconfigs, with a lossless XML core, a UUID/identity model, compile/decompile/adopt, semantic diff and simulated tests.loxuses it for the TUI's Wiring view and semantic config diffs.
- Loxone Miniserver Gen 1/2, firmware 12.0+
- Local network access (or DynDNS)
- For
lox log: Admin user - Platforms: Windows (x86_64, ARM64), macOS (x86_64, Apple Silicon), Linux (x86_64, ARM64)
This project is a an experiment. Expect rough edges. Not every Miniserver configuration has been tested. If you like the project, please help and contribute.
Use at your own risk. Commands that modify your Miniserver (e.g., config upload, reboot, update) can affect your live system. Always have a backup.