Getting Started

From docker run to your first proxied LLM request in 3 minutes

Getting Started

VoidLLM runs as a single binary with the admin UI embedded. No separate frontend server, no Node.js, no extra containers.

Quick Start (Docker)

docker run -p 8080:8080 \
  -v voidllm_data:/data \
  -e VOIDLLM_ENCRYPTION_KEY=$(openssl rand -base64 32) \
  -e VOIDLLM_ADMIN_KEY=my-admin-key-at-least-32-chars!! \
  ghcr.io/voidmind-io/voidllm:latest

Quick Start (Binary)

Download the latest binary for your platform from the releases page:

# Linux (amd64)
curl -sL https://github.com/voidmind-io/voidllm/releases/latest/download/voidllm-linux-amd64.tar.gz | tar xz
export VOIDLLM_ADMIN_KEY=$(openssl rand -base64 32)
export VOIDLLM_ENCRYPTION_KEY=$(openssl rand -base64 32)
./voidllm

Available for: Linux (amd64, arm64), Windows (amd64, arm64), macOS (amd64, arm64).

The database defaults to ./voidllm.db in the current directory. No config file required - VoidLLM starts with sensible defaults and the bootstrap wizard handles initial setup.

On first start, VoidLLM prints your credentials to stdout:

========================================
 BOOTSTRAP COMPLETE - COPY THESE NOW
========================================
  API Key:    vl_uk_a3f2...
  Email:      admin@voidllm.local
  Password:   <random>
========================================
  • Email + Password - for logging into the UI at http://localhost:8080
  • API Key (vl_uk_...) - for SDK calls and MCP connections
  • These are shown once - save them

Add a Model

Edit voidllm.yaml or use the UI (Models -> Create Model):

models:
  - name: gpt-4o
    provider: openai
    base_url: https://api.openai.com/v1
    api_key: ${OPENAI_KEY}
    aliases: [default]

See Provider Setup for all supported providers.

Send Your First Request

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer vl_uk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model": "default", "messages": [{"role": "user", "content": "hello"}]}'

VoidLLM resolves default to whatever model you configured with that alias, forwards the request, and streams the response back. Under 500 microseconds of overhead.

Connect Your IDE

Cursor / Windsurf (LLM Proxy)

Change the base URL to your VoidLLM instance:

Base URL: http://localhost:8080/v1
API Key: vl_uk_...

Claude Code (MCP Server)

Add to your MCP config:

{
  "mcpServers": {
    "voidllm": {
      "url": "http://localhost:8080/api/v1/mcp/voidllm",
      "headers": {
        "Authorization": "Bearer vl_uk_..."
      }
    }
  }
}

See IDE Integration for detailed setup.

Explore the UI

Open http://localhost:8080 and explore:

  • Dashboard - request stats, token usage, model health
  • Keys - create and manage API keys
  • Models - add models, configure aliases, view health
  • Usage - track consumption by team, user, model
  • MCP Servers - register external MCP servers
  • Playground - test models directly in the browser

Next Steps