Configuration

⚙️ Configuration

Model Hotel is configured through environment variables (startup-only) and runtime database settings (changeable without restart).

---

Environment Variables

Environment variables are read once at server startup and cannot be changed at runtime. The application loads them from a .env file (via godotenv) or from the process environment.

Required Variables

Variable	Type	Default	Description
MASTER_KEY	string	-	Master encryption key for provider API keys. Used as input to Argon2id key derivation before AES-256-GCM encryption. Must be strong and kept secret. Rotating this key invalidates ALL encrypted provider API keys - they must be re-encrypted after rotation. Generate with openssl rand -base64 32.
POSTGRES_PASSWORD	string	-	PostgreSQL password. Required if DATABASE_URL is not set. Used to construct the connection string from POSTGRES_USER, POSTGRES_HOST, and POSTGRES_DB. Generate with openssl rand -hex 16.

Note: DATABASE_URL takes precedence over the POSTGRES_* components. If DATABASE_URL is set, the other PostgreSQL variables are ignored.

Optional Variables

Variable	Type	Default	Description
DATABASE_URL	string	(constructed)	PostgreSQL connection string. If not set, constructed from POSTGRES_USER:POSTGRES_PASSWORD@POSTGRES_HOST:5432/POSTGRES_DB. E.g. postgres://user:pass@localhost:5432/modelhotel
POSTGRES_USER	string	modelhotel	PostgreSQL username (used if DATABASE_URL not set).
POSTGRES_HOST	string	db	PostgreSQL host (used if DATABASE_URL not set). In Docker Compose, this is the db service name; use localhost for local dev.
POSTGRES_DB	string	modelhotel	PostgreSQL database name (used if DATABASE_URL not set).
PORT	string	:8080	Server listen address inside the container. E.g. :8080
HOST_PORT	string	8081	Docker Compose deployment only. Port exposed on the host machine. Maps to container port 8080. Not read by the Go application - used exclusively by docker-compose.yml for port mapping.
DATA_DIR	string	./data	Directory for persistent data (admin token file, etc.). In Docker, mounted to /data.
ADMIN_TOKEN	string	(auto-generated)	Fixed admin token for API authentication. Auto-generated on first run if empty, displayed once in logs, then stored as SHA-256 hash in <DATA_DIR>/admin-token. Regenerate by deleting that file and restarting. Generate with openssl rand -hex 16.
ALLOW_HTTP_PROVIDERS	bool	false	Allow HTTP (non-HTTPS) provider base URLs. Useful for local Ollama instances or testing with mock servers.
RATE_LIMIT_ENABLED	bool	true	Hard kill-switch for rate limiting. When false, the rate-limiting middleware is always mounted but becomes a complete pass-through (no buckets allocated, no headers, no 429 responses). Cannot be overridden at runtime.
RATE_LIMIT_IP_RPS	float	30	Per-IP requests per second for the token bucket rate limiter. Clamped to 0–10000.
RATE_LIMIT_IP_BURST	int	60	Per-IP maximum burst size for the token bucket. Clamped to 1–10000.
MAX_REQUEST_SIZE	int	10485760	Maximum request body size in bytes. Clamped to 1KB–100MB. Default is 10 MB.
CORS_ORIGINS	string (comma-separated)	http://localhost:5173,http://localhost:8081	Comma-separated list of allowed CORS origins. Must include the scheme (e.g. http://). Wildcard * is explicitly rejected (incompatible with credentials=true).
ALLOWED_PROVIDER_HOSTS	string (comma-separated)	(empty)	Comma-separated list of additional allowed provider hosts. Built-in provider hosts are always allowed regardless of this setting. Hosts listed here bypass loopback blocking, so localhost can be added for local Ollama. E.g. localhost,api.example.com
TRUSTED_PROXIES	string (comma-separated CIDR)	(none)	Comma-separated list of CIDR ranges for correct client IP detection behind reverse proxies. Only needed when running behind nginx, Cloudflare, etc. E.g. 10.0.0.0/8,172.16.0.0/12
DATABASE_MAX_CONNS	int	25	Maximum database connection pool size. Clamped to 1–1000.
DATABASE_MIN_CONNS	int	5	Minimum database connection pool size. Clamped to 1–1000. Cannot exceed DATABASE_MAX_CONNS.
MODELSDEV_ENABLED	bool	true	Enable loading models.dev catalogue at startup for model enrichment data.
DEBUG_LOG	bool	false	Enable debug-level structured logging. Logs are written to stdout in JSON format.

Built-in Provider Hosts

The following provider hosts are always allowed as provider base_url values, regardless of ALLOWED_PROVIDER_HOSTS:

• api.openai.com
• api.nano-gpt.com
• api.z.ai
• api.deepseek.com
• api.anthropic.com
• ollama.com
• opencode.ai
• api.x.ai
• generativelanguage.googleapis.com
• api.cohere.com
• api.cohere.ai
• openrouter.ai

These correspond to the providers detected by DetectProviderType in internal/provider/discovery.go.

Notes

• MASTER_KEY is never used directly as an AES key. It is fed through Argon2id key derivation (per-provider random salt in v2) to produce the 256-bit AES key. See Security for details.
• ADMIN_TOKEN is stored as a SHA-256 hash. Legacy plaintext tokens are automatically migrated to hashed format on first validation.
• RATE_LIMIT_ENABLED is a hard kill-switch - when false, the rate-limiting middleware is always mounted but becomes a complete pass-through (no buckets, no headers, no 429s). The DB setting rate_limit_enabled has no effect when the env var is false.
• ALLOWED_PROVIDER_HOSTS is primarily for permitting non-standard hosts (loopback addresses for Ollama, custom provider endpoints). Built-in provider hosts never need to be listed here.
• TRUSTED_PROXIES is only needed when running behind a reverse proxy (e.g. nginx, Cloudflare). It controls which IPs are trusted to send X-Forwarded-For headers for accurate client IP logging and rate limiting.
• DATABASE_MAX_CONNS and DATABASE_MIN_CONNS are clamped to the range 1–1000. DATABASE_MIN_CONNS cannot exceed DATABASE_MAX_CONNS.
• CORS_ORIGINS explicitly rejects * wildcard - it is incompatible with credentials=true (CORS spec forbids it) and would silently break auth.

---

Database Settings

These settings are stored in the settings table and can be changed at runtime via the Settings UI or the PUT /api/settings endpoint - no restart required. Changes take effect immediately (within 30 seconds of cache TTL at most, or instantly via the subscription notification system).

API Endpoints

Method	Endpoint	Description
GET	/api/settings	Returns all settings as a JSON key-value map. Requires admin token auth.
PUT	/api/settings	Updates one or more settings. Body: {"key": "value", ...}. Max 50 keys per request. Requires admin token auth.

Settings Reference

Setting	Type	Default	Description	Valid Values / Range
discovery_interval	duration string	6h	Model auto-discovery interval. Set to 0 to disable periodic discovery entirely.	30m, 1h, 6h, 24h, 0
discovery_on_startup	bool string	true	Whether to run model discovery automatically on server startup. Skipped if last discovery was within 5 minutes.	true, false
discovery_on_provider_create	bool string	true	Whether to trigger model discovery when a new provider is created via the API. Note: This setting is checked client-side - the frontend reads it and decides whether to trigger discovery after provider creation; it is not enforced server-side.	true, false
log_retention	duration string	(empty)	How long to keep request logs. Empty or unrecognised values = keep forever. Cleanup runs hourly.	1h, 1d/24h, 1w/168h, 1m/720h, (empty)
stale_request_timeout	duration string	30m	Timeout for marking in-progress request logs as failed. Rows stuck in pending or streaming state longer than this are marked failed.	30m, 1h, etc.
request_timeout	duration string	1m	Per-request timeout duration. Base timeout for non-streaming requests. Streaming requests use 10x this value.	30s, 1m, 5m, 10m
failover_on_rate_limit	bool string	true	Whether to failover to the next provider when an upstream returns HTTP 429. 5xx errors always trigger failover.	true, false
circuit_breaker_enabled	bool string	true	Enable per-provider circuit breaker for hotel/ failover routes. When open, the provider is skipped during failover selection.	true, false
circuit_breaker_threshold	int	5	Consecutive failures before a provider's circuit opens.	1–100
circuit_breaker_cooldown	duration string	60s	Duration an open circuit stays open before transitioning to half-open.	30s, 60s, 120s, etc.
rate_limit_enabled	bool string	true	Runtime toggle for rate limiting. Overridden by RATE_LIMIT_ENABLED env var - if env var is false, this setting has no effect.	true, false
rate_limit_ip_enabled	bool string	true	Runtime toggle for per-IP rate limiting. Only effective when RATE_LIMIT_ENABLED=true.	true, false
rate_limit_ip_rps	float	30	Per-IP requests per second. Set to 0 for unlimited per-IP rate.	0–10000
rate_limit_ip_burst	int	60	Per-IP burst size for token bucket.	1–10000
rate_limit_rps	float	10	Per-virtual-key requests per second. Set to 0 to disable per-key rate limiting (makes every bucket unlimited).	0–10000
rate_limit_burst	int	20	Maximum burst bucket size per virtual key.	1–10000
rate_limit_max_wait_ms	int	200	Maximum wait time (ms) in the rate-limiter queue before rejecting with 429. Shared by both per-IP and per-key limiters.	0–10000
key_cache_ttl	duration string	10m	Provider key decryption cache TTL. Controls how long decrypted provider API keys are held in memory before re-derivation.	(varies)

Rate Limiting Details

The rate limiting system has two layers, both using token buckets (backed by golang.org/x/time/rate):

Per-IP rate limiting (DoS protection, always-on when enabled):

• Applied before authentication, before the per-key limiter
• rate_limit_ip_rps controls the per-IP refill rate (default 30)
• rate_limit_ip_burst controls the per-IP maximum burst size (default 60)
• rate_limit_ip_enabled toggles this layer at runtime (requires RATE_LIMIT_ENABLED=true)
• Independent bucket per client IP address

Per-virtual-key rate limiting (usage control):

• Each key gets its own independent bucket
• rate_limit_rps controls the refill rate (tokens per second, default 10)
• rate_limit_burst controls the maximum bucket size (default 20)
• Setting rate_limit_rps=0 makes every bucket unlimited (no per-key rate limiting)

Shared settings:

• rate_limit_max_wait_ms (default 200) - maximum time a request waits in the rate-limiter queue before being rejected with 429. Applies to both per-IP and per-key limiters.
• The RATE_LIMIT_ENABLED environment variable is a hard kill-switch - when false, both layers are always mounted but become a complete pass-through (no buckets, no headers, no 429s)
• When rate limiting is re-enabled after being disabled, all existing buckets are reset to ensure fresh state
• Unused buckets are cleaned up by a periodic cleanup task that runs every 5 minutes and removes entries that have been idle for more than 10 minutes

When a request is rate-limited, the response includes:

• Retry-After: <seconds> - When the client can retry
• X-RateLimit-Limit: <rate> - The refill rate
• X-RateLimit-Remaining: <tokens> - Remaining tokens in the bucket
• X-RateLimit-Burst: <burst> - The burst capacity
• X-RateLimit-Scope: <ip|key> - Indicates whether the rate limit applies to ip (per-IP) or key (per-virtual-key)

---

Frontend Settings (localStorage)

User preferences are stored in localStorage (client-side only, never sent to the server):

Key	Description
adminToken	Admin authentication token (used for API calls)
theme	dark/light
accentColor	Hex color string
uiStyle	cyber-terminal, glassmorphism-lite, or default
toastPosition	Toast notification position
toastTimeout	Toast display duration (ms)
persistChat	Whether to persist chat state across sessions
persistConversation	Whether to persist conversation state
persistArena	Whether to persist arena state and history
sidebarChatSubMode	chat/conversation
sidebarArenaSubMode	competition/compare
sidebarLogsSubMode	request/app
sidebarQuotaDisabled	Whether to hide the quotas pill in sidebar (inverted: true = hidden)
sidebarQuotaRefreshMin	Sidebar quota refresh interval in minutes
dashboardRefreshSec	Dashboard refresh interval in seconds

Settings Page Sections

The Settings page has 8 collapsible sections:

Model Discovery

Backend settings: discovery_interval, discovery_on_startup, discovery_on_provider_create

Appearance (localStorage only)

• UI Style: cyber-terminal, glassmorphism-lite - stored in localStorage uiStyle (note: clean-saas is not available)
• Theme: dark / light - stored in localStorage theme
• Accent Color: 10 preset swatches + custom hex picker - stored in localStorage accentColor

Note: theme, ui_style, and accent_color are not in the backend AllowedSettings - they are localStorage-only and cannot be set via PUT /api/settings.

Toast Notifications (localStorage only)

• Position: 6-position visual picker - stored in localStorage toastPosition
• Auto-dismiss: 1s–15s slider - stored in localStorage timeout

Sidebar Quotas (localStorage only)

• Show Quotas Pill: Toggle - stored in localStorage sidebarQuotaDisabled (inverted: true = hidden)
• Refresh Interval: 1/2/5/10/15/30 minutes or Disabled - stored in localStorage sidebarQuotaRefreshMin

Dashboard Refresh (localStorage only)

• Refresh Interval: 10s/30s/1m/2m/5m/10m/Disabled - stored in localStorage dashboardRefreshSec

Logging

Backend settings: log_retention, stale_request_timeout Also includes purges for request logs and app logs.

Data Storage (localStorage only)

• Session Persistence: Toggle for chat, arena, and conversation state across page reloads
• Arena History: Save match history toggle, limit (10/25/50/100), clear button
• Cache & Resets: Clear provider quota cache, reset dismissed error banners

Rate Limiting

Backend settings: rate_limit_enabled, rate_limit_rps, rate_limit_burst, rate_limit_ip_enabled, rate_limit_ip_rps, rate_limit_ip_burst, rate_limit_max_wait_ms

Screenshots

Settings page - showing the 8 collapsible sections: Model Discovery, Appearance, Toast, Sidebar Quotas, Dashboard Refresh, Logging, Data Storage, and Rate Limiting.

Settings page - Appearance section expanded, showing UI Style cards (cyber-terminal, glassmorphism-lite), Theme toggle, and Accent Color picker.

Settings page - Rate Limiting section expanded, showing the enable toggle, RPS selector, and Burst selector.

---

Docker Compose Configuration

The docker-compose.yml sets up the following services:

Services

app - Model Hotel Server

Configuration	Value	Description
Build	.	Builds from the root Dockerfile
Ports	${HOST_PORT:-8081}:8080	Maps host port (default 8081) to container port 8080
Environment	See below	Environment variables passed to the container
Volumes	./.data:/data	Persistent data storage (admin token, etc.)
Volumes	/var/run/docker.sock:/var/run/docker.sock:ro (commented out by default)	Read-only Docker socket access for container stats in sidebar
Depends on	db (healthy)	Waits for PostgreSQL to be ready

Environment variables (docker-compose.yml):

environment:
  - MASTER_KEY=${MASTER_KEY:?MASTER_KEY must be set in .env}
  - POSTGRES_USER=${POSTGRES_USER:-modelhotel}
  - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set in .env}
  - POSTGRES_HOST=db
  - POSTGRES_DB=${POSTGRES_DB:-modelhotel}
  - ADMIN_TOKEN=${ADMIN_TOKEN:-}
  - ALLOW_HTTP_PROVIDERS=false
  - DATA_DIR=/data
  - RATE_LIMIT_ENABLED=true
  - DEBUG_LOG=false
  - CORS_ORIGINS=http://localhost:5173,http://localhost:${HOST_PORT:-8081}
  - ALLOWED_PROVIDER_HOSTS=

db - PostgreSQL 16

Configuration	Value	Description
Image	postgres:16-alpine	PostgreSQL 16 on Alpine Linux
Ports	5432:5432	Exposed for local development
Environment	POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB	Database credentials
Volumes	./.data/pgdata:/var/lib/postgresql/data	Persistent database storage
Healthcheck	pg_isready -U ${POSTGRES_USER}	Checks database readiness every 5s

Quick Start

git clone https://github.com/hugalafutro/model-hotel.git
cd model-hotel

cp .env.example .env
nano .env          # set a strong MASTER_KEY and POSTGRES_PASSWORD

docker compose up --build

Get the admin token:

docker compose logs app | grep "ADMIN_TOKEN="

If you lose the token, delete .data/admin-token and restart to generate a new one.

You can also set a fixed admin token via the ADMIN_TOKEN environment variable in your .env file.

---

Dockerfile Configuration

The Dockerfile uses a multi-stage build:

Stage 1: Frontend Build

• Base: node:20-alpine
• Package manager: pnpm (via corepack)
• Working directory: /app/web
• Build command: pnpm run build
• Output: dist/ directory (embedded in backend)

Stage 2: Backend Build

• Base: golang:1.25-alpine
• Working directory: /app
• Build command: go build -o server ./cmd/server/
• Embeds: Frontend dist/ into cmd/server/static/

Stage 3: Final Runtime Image

• Base: alpine:latest
• Dependencies: ca-certificates, postgresql-client
• Working directory: /app
• Binary: ./server
• Exposed port: 8080
• Healthcheck: wget --spider http://localhost:8080/health (30s interval, 40s start period)
• CMD: ["./server"]

Build Artifacts

Path	Source	Purpose
/app/server	Backend binary	Main application executable
/app/web/dist/	Frontend build	Static assets served by the backend
/app/migrations/	DB migrations	Reference copy (migrations are embedded in binary)

---

Configuration Files Reference

.env.example

Template file showing all available environment variables:

# Required: Generate strong secrets before deploying
MASTER_KEY=
POSTGRES_PASSWORD=

# PostgreSQL (used if DATABASE_URL not set)
POSTGRES_USER=modelhotel
POSTGRES_HOST=db
POSTGRES_DB=modelhotel

# Server configuration
PORT=:8080
HOST_PORT=8081  # Docker Compose only - not read by the Go application
# DISCOVERY_INTERVAL=30m  # DB setting only - set via PUT /api/settings, not read from env
DATA_DIR=./data
ADMIN_TOKEN=

# Feature flags
ALLOW_HTTP_PROVIDERS=false
RATE_LIMIT_ENABLED=true
RATE_LIMIT_IP_RPS=30
RATE_LIMIT_IP_BURST=60
MAX_REQUEST_SIZE=10485760
CORS_ORIGINS=http://localhost:5173,http://localhost:8081
ALLOWED_PROVIDER_HOSTS=
TRUSTED_PROXIES=
DATABASE_MAX_CONNS=25
DATABASE_MIN_CONNS=5
MODELSDEV_ENABLED=true
DEBUG_LOG=false

---

Summary

Category	Count	Runtime Changeable
Environment Variables	22	No (restart required)
Database Settings	18	Yes (via API/UI)
Frontend localStorage	14	Yes (client-side only)

Key Architecture Points:

1. Environment variables are loaded once at startup via godotenv.Load() and the config.Load() function.
2. Database settings use a 30-second cache with change notifications via Subscribe() for immediate updates.
3. Rate limiting has a hard kill-switch (RATE_LIMIT_ENABLED env var) that completely disables the middleware when false.
4. Provider host validation always allows built-in providers; ALLOWED_PROVIDER_HOSTS is only for custom/local providers.
5. Admin token is auto-generated on first run and stored as a SHA-256 hash.