llmbox-server

Overview ¶

Command llmbox-server runs the llmbox server that manages sandboxed boxes ("llmboxes") — the box infrastructure; each box's workload is installed by the spoke's init script.

One process serves everything on a single HTTP port (http_addr):

/api/v1/...     box-control JSON API — the UI and the stand-alone llmbox-mcp binary call it
/admin, /signin admin web UI and the OIDC sign-in that gates it and the per-box proxies (+ health)

The MCP protocol itself is served by a separate binary (llmbox-mcp), which forwards every call to the box-control API over HTTP. The box-control API is authenticated: callers present an API key as a bearer token (minted with `llmbox-server apikey add`), and the admin web app uses the signed-in admin's login cookie plus a CSRF header.

Configuration is a YAML file (default ./llmbox.yaml, override with --config). Every field is optional; unset fields fall back to built-in defaults:

http_addr:    ":8080"                  # HTTP listen address (UI + box-control API)
public_url:   "http://localhost:8080"  # external base URL for auth links
auth_ttl:     "5m"                      # how long a box may stay un-authenticated (Go duration)
state_file:   "llmbox-sessions.db"     # SQLite file persisting the session registry

The hub runs no box backend of its own, so it holds no box-provisioning config: the box image, resource caps, and backend are the spoke's concern and are set with llmbox-spoke flags (e.g. --image).

By default the single HTTP server is served in the clear and a loud startup warning is logged, since it is meant to sit behind a TLS-terminating reverse proxy. To terminate TLS in-process instead, enable the tls block:

tls:
  enabled:   true
  cert_file: "/etc/llmbox/tls-cert.pem"  # PEM certificate (full chain, leaf first)
  key_file:  "/etc/llmbox/tls-key.pem"   # PEM private key matching cert_file

Box lifecycle hooks (optional). hooks is a list of external executables llmbox runs at box.create and box.destroy, exchanging JSON per the hookproto contract. A hook may inject files into each box and persist opaque state; this is how integrations like granular plug in without llmbox depending on them:

hooks:
  - /opt/granular-llmbox/hook