millivolt Install millivolt
StartInstall and first run
On this page

Install and first run

Install millivolt from the published image or a source checkout, set the operator credential, and send a first request on each client protocol. The quickstart is the short form of the same procedure; this page carries the full path.

Before you start

The container path needs Linux with Docker Engine and the Compose plugin. No Go, Node or source checkout is needed for it. The source path needs the Go toolchain required by go.mod.

Install with Docker Compose

curl -fsSL https://raw.githubusercontent.com/LLM-4-People/millivolt/main/compose.yaml -o compose.yaml
export MILLIVOLT_OPERATOR_TOKEN='replace-with-a-long-random-value'
docker compose up -d

Open http://127.0.0.1:8080/ and sign in with that token. If the container exits, run docker compose logs --tail 50.

The Compose file publishes on loopback only. It keeps history and settings in named volumes, runs non-root with a read-only root filesystem, and accepts MILLIVOLT_PORT for an unused host port. For bind mounts, pre-create directories writable by UID/GID 65532:65532; see persistent state. For image selection, backups, updates, shutdown, or protected ingress, see container operation and the reverse-proxy guide.

The published image is ghcr.io/llm-4-people/millivolt:main for amd64 and arm64. Version tags identify releases; pin a digest when exact bytes matter. See versions and images.

Install from a source checkout

Install the Go toolchain required by go.mod, then:

git clone https://github.com/LLM-4-People/millivolt.git
cd millivolt
test -e proxy.yaml || cp proxy.example.yaml proxy.yaml
export MILLIVOLT_OPERATOR_TOKEN='replace-with-a-long-random-value'
go run ./cmd/proxy -config proxy.yaml -listen 127.0.0.1:8080

For isolated development and checks, see Contributing.

Environment and defaults

The Compose inputs are environment variables; their defaults live in compose.yaml, not server configuration. Supply them consistently through the environment or an ignored local .env file.

Variable Meaning
MILLIVOLT_OPERATOR_TOKEN The single operator credential. It is read once at boot from the process environment and never from proxy.yaml, so rotating it requires a real process restart. A nonempty value shorter than 16 or longer than 512 bytes fails the boot. Unset or empty leaves the dashboard denied.
MILLIVOLT_IMAGE Image reference; defaults to ghcr.io/llm-4-people/millivolt:main.
MILLIVOLT_PORT Loopback host port; default 8080.
MILLIVOLT_STOP_GRACE_PERIOD Container stop grace; default 30s.
MILLIVOLT_MEM_LIMIT Container memory ceiling; default 1g.
MILLIVOLT_PIDS_LIMIT Process and thread ceiling; default 512.

docker compose config shows the resolved deployment. A source deployment configures the same service through -config PATH (default local proxy.yaml), -listen ADDRESS and -db-path PATH; the generated example and the Settings schema are the field reference. See configuration.

Send a first request

Point a client at the proxy and supply the upstream base URL and key on each request. The proxy registers no providers or keys. X-Proxy-Format selects a different upstream protocol; absent, the request passes through. See protocol and adapters.

OpenAI Chat Completions:

curl -sS http://127.0.0.1:8080/v1/chat/completions \
  -H "X-Proxy-Base-URL: $UPSTREAM_BASE_URL" \
  -H "Authorization: Bearer $UPSTREAM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$UPSTREAM_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}"

OpenAI Responses:

curl -sS http://127.0.0.1:8080/v1/responses \
  -H "X-Proxy-Base-URL: $UPSTREAM_BASE_URL" \
  -H "Authorization: Bearer $UPSTREAM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$UPSTREAM_MODEL\",\"input\":\"hello\"}"

Anthropic Messages, using the native upstream's own auth header, prefix and API version:

curl -sS http://127.0.0.1:8080/v1/messages \
  -H "X-Proxy-Base-URL: $UPSTREAM_BASE_URL" \
  -H "X-Proxy-Key: $UPSTREAM_API_KEY" \
  -H 'X-Proxy-Auth-Header: x-api-key' \
  -H 'X-Proxy-Auth-Prefix;' \
  -H "anthropic-version: $ANTHROPIC_VERSION" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$UPSTREAM_MODEL\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}"

The semicolon in -H 'X-Proxy-Auth-Prefix;' is important: curl sends a present empty header. -H 'X-Proxy-Auth-Prefix:' instead omits it, leaving the proxy's Bearer default. A response means the proxy answered; check the status code for the upstream outcome. The request appears in the dashboard.

On a shared Compose network, use http://millivolt:8080/v1 instead of loopback. /v1/chat/completions, /v1/responses and /v1/messages are all available. Each can reach Chat, Responses or Anthropic upstreams; only a Chat client can target the Cursor bridge. Read upstream compatibility and cross-protocol translation.

The dashboard

The dashboard is the site root, http://127.0.0.1:8080/. It asks for the operator token once per browser tab, keeps it in sessionStorage, attaches it to gated calls only and drops it as soon as the server rejects it. The same credential gates /metrics/*, /admin/* and /mcp; transparent inference does not use it. See operator access for the canonical open-path list.

Documentation routes by task. For the next step, read configuration before changing settings, or the dashboard tour to find the request you just sent.

search

Search the docs

Search titles, headings, and body text. Press / from anywhere.