voidcraft-world-bridge

A small loopback server that lets voidcraft.world talk to your own local LLM, so it can answer questions about your worlds or command a side in Arena World.

uvx voidcraft-world-bridge

That's the whole install. It finds your model server on its own and listens on http://127.0.0.1:7682 until you press Ctrl-C:

voidcraft-world-bridge 0.1.1 — listening on http://127.0.0.1:7682
  plugin: local-llm  → http://127.0.0.1:7682/plugin/local-llm/…
  local model:  Ollama at http://127.0.0.1:11434 → qwen3.6:35b-a3b
  Ctrl-C to stop

Your model server

Run any one of these and the bridge finds it, asking in this order:

Anything else that speaks the OpenAI API (vLLM, Jan, a custom port) works too. Point the bridge at it, and it asks only that server:

VOIDCRAFT_LOCAL_LLM_URL=http://127.0.0.1:8000/v1 uvx voidcraft-world-bridge

Which model answers: the strongest chat model you have, by a built-in preference list (Qwen 3.6 35B-A3B first). Embedding models are never picked. Pin one with VOIDCRAFT_LOCAL_LLM_MODEL=<name>. The bridge never downloads a model; install one with your server first (ollama pull qwen3.5:9b is a good small start).

What the OpenAI-compatible path cannot do: set the context size per request. Load your model with enough context (16K or more) in the server itself.

Why it exists

A web page cannot call localhost services directly: CORS and Chrome's Local Network Access stop it, on purpose. The bridge is the one door through, and it is narrow:

• Loopback only. It binds 127.0.0.1. There is no flag to bind anything wider.
• Origin allowlist. Only voidcraft.world and pages served from your own machine may call it. Any other site gets a 403.
• DNS-rebinding guard. A request addressed to any hostname other than localhost / 127.0.0.1 / [::1] gets a 403, even when the origin looks right.
• No shell, no files. It routes chat requests to your model server and nothing else.
• Your prompts are not kept. A request is dropped from memory once it is answered.
• Stdlib only. Zero third-party dependencies.

The local-llm API

Mounted at /plugin/local-llm/:

Generation is a job, not a request: one answer can take a minute, and one model generates one answer at a time — two at once would only split the same memory bandwidth.

Commands

voidcraft-world-bridge              # serve (foreground)
voidcraft-world-bridge status       # is one running? what does it mount?
voidcraft-world-bridge --version
voidcraft-world-bridge --port 7700  # or VOIDCRAFT_BRIDGE_PORT=7700

Plugins

Everything the bridge can do is a plugin mounted at /plugin/<name>/…. local-llm is built in; add your own by pointing the bridge at a directory containing a bridge_plugin.py:

VOIDCRAFT_BRIDGE_PLUGINS=/path/to/my-plugin voidcraft-world-bridge

or list directories in ~/.config/voidcraft-world-bridge/plugins.json:

{ "version": 1, "plugins": ["/path/to/my-plugin"] }

A plugin module defines PLUGIN_NAME and create_plugin(context), returning an object with routes(), handle_get(subpath, query) and handle_post(subpath, query, body). Handlers return (status, dict) for JSON or (status, bytes, content_type) for a raw page. POST bodies are capped at 4 KB unless the plugin sets max_body_bytes. A plugin that fails to load is skipped, and a handler that raises becomes a 500; a plugin can never take the bridge down. Full contract: voidcraft_world_bridge/plugins.py.

A complete, runnable one to copy: examples/hello-plugin — one file, every part of the contract, loaded and exercised by the test suite so it cannot drift from it.

VOIDCRAFT_BRIDGE_PLUGINS=$PWD/examples/hello-plugin voidcraft-world-bridge --port 7791
curl 'http://127.0.0.1:7791/plugin/hello/greeting?name=you'

Development

uv sync
uv run pytest                                # no model server needed; every test fakes one
uv run voidcraft-world-bridge --port 7791    # a spare port, if a bridge already holds 7682

CONTRIBUTING.md has the two rules every change must keep (stdlib only, nothing private) and the checks CI runs. Found something exploitable? SECURITY.md says how to report it privately.

Remote access (optional)

To reach the bridge through tailscale serve, name the machine explicitly:

VOIDCRAFT_BRIDGE_ALLOWED_HOSTS=mymac.tailXXXX.ts.net voidcraft-world-bridge

Never use tailscale funnel or a public tunnel: that publishes your bridge to the internet.