Configuration

All settings are configured via environment variables prefixed with MYCELLM_. They can be set in:

• ~/.config/mycellm/.env (written by mycellm init)
• Shell environment
• Docker -e flags

Environment Variables

Variable	Default	Description
MYCELLM_API_KEY	(none)	API key for dashboard/API authentication
MYCELLM_BOOTSTRAP_PEERS	(none)	Bootstrap node addresses (host:port, comma-separated)
MYCELLM_HF_TOKEN	(none)	HuggingFace token for gated models + higher rate limits
MYCELLM_DB_URL	SQLite	Database URL (postgresql+asyncpg://user:pass@host/db)
MYCELLM_TELEMETRY	false	Opt-in anonymous usage stats
MYCELLM_LOG_LEVEL	INFO	Log verbosity: DEBUG, INFO, WARNING, ERROR
MYCELLM_RELAY_BACKENDS	(none)	Relay endpoints (comma-separated OpenAI-compatible URLs)
MYCELLM_MODEL_DIR	~/.local/share/mycellm/models	GGUF model download directory
MYCELLM_DATA_DIR	~/.local/share/mycellm	All persistent data
MYCELLM_CONFIG_DIR	~/.config/mycellm	Configuration directory
MYCELLM_API_HOST	127.0.0.1	API bind address
MYCELLM_API_PORT	8420	API port
MYCELLM_QUIC_PORT	8421	QUIC transport port (UDP)
MYCELLM_EXTERNAL_HOST	(none)	Public IP override for NAT traversal
MYCELLM_NODE_NAME	hostname	Display name for this node
MYCELLM_INITIAL_CREDITS	100.0	Starting credit balance
MYCELLM_PREFLIGHT_KV_AWARE	true	KV-aware model-load preflight on MLX backends (since 0.6.0). Estimates weights + KV cache against the Metal working-set ceiling before loading
MYCELLM_PREFLIGHT_ACTION	clamp	What to do when a load won’t fit: warn (load anyway), clamp (reduce context length to the largest that fits), or reject
MYCELLM_PREFLIGHT_MIN_CTX_LEN	2048	Never clamp context below this
MYCELLM_MEMORY_WATCH_ENABLED	true	Runtime memory-pressure watcher (macOS): kernel WARN clears the Metal cache; CRITICAL evicts idle local models before the OOM killer fires. Evicted models stay enabled and restore on restart
MYCELLM_MEMORY_WATCH_INTERVAL	10.0	Seconds between pressure polls
MYCELLM_MEMORY_WATCH_EVICT	true	Allow CRITICAL-pressure eviction of idle models (set false for cache-clear only)
MYCELLM_MEMORY_WATCH_IDLE_SECONDS	60.0	A model must be idle this long before it is eviction-eligible
MYCELLM_TRUSTED_PROXIES	127.0.0.0/8,::1	Reverse proxies whose X-Forwarded-For may be believed (comma-separated IPs/CIDRs). See the warning below
MYCELLM_QUEUE_ENABLED	true	Async job queue. Off makes /v1/jobs answer 503 queue_disabled
MYCELLM_QUEUE_MAX_CONCURRENT	1	Queued jobs this node runs at once
MYCELLM_QUEUE_POLL_INTERVAL	5.0	Seconds between scheduler polls while work is pending
MYCELLM_MLX_PREFILL_STEP_SIZE	0	Prefill chunk size (tokens) for MLX generation; 0 = mlx-lm default (2048). Lower it (e.g. 512) on memory-tight nodes to shave the prefill transient

Running behind a reverse proxy

Set this, or every per-IP limit becomes one shared bucket

MYCELLM_TRUSTED_PROXIES decides whose X-Forwarded-For header mycellm will believe. Without it, a node behind nginx/Caddy sees every caller as the proxy — so the public chat rate limit, the node-announce limiter and the anon budget all apply to the whole internet collectively rather than per visitor.

A containerised deployment is the common case: the container sees the Docker bridge gateway, not the client.

# Caddy on the host, mycellm in a container on the default bridge
MYCELLM_TRUSTED_PROXIES="127.0.0.0/8,::1,172.17.0.0/16"

Only list addresses you control. The header is written by the caller, so trusting an address you do not own lets anyone present a fresh IP per request and evade every limit. mycellm reads the header only when the TCP peer — which cannot be forged — is inside this list, and then walks the chain right-to-left to the first hop it did not put there itself.

Ports

Port	Protocol	Purpose
8420	TCP	HTTP API + Dashboard
8421	UDP	QUIC P2P transport
8422	UDP	DHT discovery (optional)

File Layout

~/.local/share/mycellm/
├── keys/              # Ed25519 account + device keys
├── certs/             # Device certificates
├── tls/               # Self-signed TLS for QUIC
├── models/            # Downloaded GGUF files
├── federation/        # Network identity + memberships
├── secrets.json       # Encrypted API keys (Fernet)
├── mycellm.db         # SQLite database
└── model_configs.json # Saved model configurations

~/.config/mycellm/
└── .env               # Environment overrides

PostgreSQL

For larger networks, switch from SQLite to PostgreSQL:

MYCELLM_DB_URL="postgresql+asyncpg://user:pass@localhost/mycellm"

Install the PostgreSQL driver:

pip install "mycellm[postgres]"