Skip to content
librezooPublic

About

Local host software for the USB-C Voloo Switch: CLI, MCP server for AI agents, HTTP API and web dashboard

Topics

Resources

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

voloo

A power switch you can program.
Control the USB-C voloo Switch from a CLI, an AI agent (MCP), a local HTTP API or a web dashboard.

CI npm Release License: Apache-2.0 Platforms: macOS, Linux, Windows Node.js 18 or newer MCP server included Rust

The voloo Switch: yellow and purple enclosure, green spring terminals, USB-C port
AI-assisted product rendering

One voloo program talks to every Switch over its own USB cable. No driver is needed on macOS, Linux or Windows 10/11.

voloo only switches externally supplied power; it is not a power source. OFF does not mean the load terminals are at zero volts. Use discharge to confirm VOUT ≤ 1 V.

Website · User guide · 中文使用说明 · Reference · Changelog

Install

Requires Node.js 18 or newer.

npm install -g @librezoo/voloo@latest

To update, run the same command, then restart the background process once so it also runs the new version:

voloo daemon stop
voloo ls

If npm reports a permission error (EACCES), do not use sudo; see the install help on the website.

Quick start

voloo ls                 # connected devices, state and active faults
voloo name DEV bench-a   # optional nickname; DEV is a UID or nickname
voloo on bench-a         # switch on and confirm by reading status back
voloo discharge bench-a  # switch off and confirm VOUT ≤ 1 V
voloo ui                 # live web dashboard
voloo demo               # the dashboard with simulated devices, no hardware

Every power command is confirmed by reading the device state. A lost acknowledgement is never answered by resending a command; the result is either confirmed or reported as unknown. Add --json for machine-readable output. See the reference for all commands, exit codes, the HTTP API, configuration and logs.

AI agents (MCP)

Any MCP client that runs a stdio server uses the same command:

Client Setup
Claude Code claude mcp add voloo -- voloo mcp
Codex ~/.codex/config.toml: [mcp_servers.voloo] command = "voloo" args = ["mcp"]
Cursor, Windsurf, Cline, VS Code, Gemini CLI, … {"command": "voloo", "args": ["mcp"]}

Tools: voloo_list_devices, voloo_get_status, voloo_power (on, off, discharge, cycle), voloo_set_nickname, voloo_get_log. Set [mcp] read_only = true in the configuration to let agents read but not switch. Tested clients are listed in MCP client compatibility.

Firmware

voloo firmware update DEV installs the newest published firmware that fits the device and the installed voloo, verifies its checksum and the result, and keeps the previous image for voloo firmware rollback DEV. The device must be idle and OFF with valid measurements and VOUT ≤ 1 V. See firmware updates for the limits and recovery steps.

Documentation

User guide · 中文 Wiring, first use, dashboard, troubleshooting
Quick start · 中文 Two-page wiring and first-use sheet
Reference Commands, exit codes, HTTP API, configuration, logs, how the background process works
Firmware updates · 中文 Updating, rollback, recovery
Changelog · Release notes What changed in each version
Security Reporting vulnerabilities

Development

cargo build --release   # target/release/voloo
cargo test              # simulated devices only; never touches real hardware
cargo fmt --check && cargo clippy --all-targets -- -D warnings
node --test packaging/npm/publish.test.mjs tests/web.test.mjs
Path Contents
src/ The single Rust implementation: CLI, background process, MCP, HTTP API, serial link, firmware updates
web/ The dashboard (static files served by the program)
tests/ Integration tests with a simulated device
packaging/ npm and PyPI packaging
firmware/x035/ Published firmware manifest and encrypted package

Other languages integrate through the HTTP API, --json or MCP rather than separate SDKs. Commits follow Conventional Commits and versions follow Semantic Versioning.

License

Apache-2.0

About

Local host software for the USB-C Voloo Switch: CLI, MCP server for AI agents, HTTP API and web dashboard

Topics

Resources

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages