HiggsHole

A self-hosted AI image and video generation console with a browsable media library, backed by the OpenRouter API and exposed to local AI agents over MCP.

Status: implemented. Web UI, REST API, MCP server and systemd unit are in place and covered by an offline test suite. See the design specification.

What it does

• Text-to-image, text-to-video, image-to-image and image-to-video generation through a single OpenRouter API key
• Model picker built from OpenRouter's live capability catalogue — no hardcoded model list, so new models appear without a code change
• Generated media stored on local disk with metadata embedded in the files themselves, browsable and playable in the web UI
• Any result can be fed back in as a reference for an edit or improvement pass, with the lineage recorded
• An MCP server (stdio) exposing the same functionality to locally running AI agents
• Spend controls: provider-enforced key limits, a local ledger of actual costs, and a daily cap

What it deliberately does not do

• No prompt rewriting — prompts are passed to the provider verbatim
• No authentication — intended for a trusted LAN
• No multi-user support
• No batch generation — n is fixed at 1 so every generation has its own cost record

Quick start

uv sync
uv run pytest -q          # the whole suite, offline and free
uv run higgshole          # serves http://127.0.0.1:8077

The suite makes no network requests and costs nothing: a socket-blocking fixture enforces that rather than trusting convention. The single billable test is opt-in behind HIGGSHOLE_LIVE_TESTS and skipped by default.

MCP tools

Eleven tools, each a thin translation of one REST call — see docs/mcp.md for client registration:

Tool	Behaviour
list_models	Image and video models with capability constraints
generate_image	Synchronous; returns the finished asset
generate_video	Returns a job ID immediately — does not block
get_job	Status, with optional bounded long-polling
upload_asset	Ingests a local file, returning a reusable asset ID
list_media	Browse with filters
get_media	Full metadata for one item, including lineage
delete_media	Removes a generation, its files and its thumbnails
list_projects	Enumerate projects
create_project	Create a project
get_budget	Provider-authoritative credit plus local cap status

Every asset-returning tool provides both the local filesystem path and the HTTP URL, since agents run on the same host. Costs are strings or null — never 0 to represent an unknown cost.

Design notes

The specification records several verified corrections to OpenRouter's published documentation, including the true job-status enumeration, the unreliability of client-side video cost estimation, and the ephemerality of result URLs. These were established against the live API and its OpenAPI specification rather than the prose docs, which contradict it in places.

Requirements

• Python 3.12+
• ffmpeg / ffprobe
• An OpenRouter API key

Runs anywhere Python and ffmpeg run. A systemd unit is provided for boot-time startup on Linux — see docs/deployment.md — but nothing in the architecture depends on it.

Configuration

Everything is configured through environment variables, readable from a .env file — see .env.example for the full list with defaults. By default the app writes under ${XDG_DATA_HOME:-~/.local/share}/higgshole and ${XDG_STATE_HOME:-~/.local/state}/higgshole and binds to 127.0.0.1, so a fresh clone runs unprivileged with no setup.

Exposing it to your local network is a deliberate act: change HIGGSHOLE_BIND_HOST. There is no authentication, by design.

If you set a daily spend cap, also set a credit limit on the OpenRouter key itself. That limit is enforced provider-side and is the only guard that cannot be defeated by a bug in this application.

Licence

MIT