Configuration Reference

Configuration Reference

Every configuration option in MuxCore — config file keys, environment variables, CLI flags, and their defaults.

---

Config File (muxcore.json)

Place muxcore.json in the working directory, or override the path with MUXCORE_CONFIG.

Top-Level Keys

Key	Type	Description
server	ServerConfig	HTTP server settings
grpc	GRPCConfig	gRPC mesh settings
log	LogConfig	Structured logging
database	DatabaseConfig	Database connection (driver + URL)
cache	CacheConfig	Cache connection (driver + URL)
audit	AuditConfig	Audit logging
modules	map[string]any	Per-module arbitrary configuration

server

Key	Type	Default	Description
addr	string	:8080	HTTP listen address (validated with net.ResolveTCPAddr)
read_timeout	int	15	Read timeout in seconds
write_timeout	int	15	Write timeout in seconds
cert_file	string	""	Path to TLS certificate PEM file
key_file	string	""	Path to TLS private key PEM file

grpc

Key	Type	Default	Description
addr	string	:9090	gRPC listen address (validated with net.ResolveTCPAddr)
cert_file	string	""	Path to TLS certificate PEM file
key_file	string	""	Path to TLS private key PEM file
mtls_enabled	bool	false	Require mutual TLS
ca_cert_file	string	""	Path to CA cert for mTLS client verification
seed_nodes	[]string	[]	Cluster seed node addresses (host:port)
join_token	string	""	Pre-shared token required to join the cluster
max_message_size_mb	int	32	gRPC max message size in MB (affects storage streaming). Must be positive.

log

Key	Type	Default	Description
level	string	info	Log level: debug, info, warn, error
format	string	text	Log format: text, json

database

Key	Type	Default	Description
driver	string	""	Database driver (provided by database module)
url	string	""	Database connection URL (credentials redacted in logs)

cache

Key	Type	Default	Description
driver	string	""	Cache driver (provided by cache module)
url	string	""	Cache connection URL (credentials redacted in logs)

audit

Key	Type	Default	Description
path	string	""	File path for JSONL audit log; empty = disabled
max_size_mb	int	100	Rotate audit log when file exceeds this size in MB
max_rotated_files	int	5	Number of rotated log files to keep (.1, .2, …)

storage

Per-operation timeout for storage provider calls. A hung provider cannot block callers beyond these deadlines.

Key	Type	Default	Description
read_timeout_seconds	int	30	Deadline for Get, Exists, Stat, List, Stream
write_timeout_seconds	int	300	Deadline for Put (5 minutes — large files need time)
delete_timeout_seconds	int	30	Deadline for Delete, Move

Example muxcore.json

{
  "server": {
    "addr": ":8080",
    "read_timeout": 15,
    "write_timeout": 15,
    "cert_file": "/etc/ssl/server-cert.pem",
    "key_file": "/etc/ssl/server-key.pem"
  },
  "grpc": {
    "addr": ":9090",
    "cert_file": "/etc/ssl/grpc-cert.pem",
    "key_file": "/etc/ssl/grpc-key.pem",
    "mtls_enabled": true,
    "ca_cert_file": "/etc/ssl/ca.pem",
    "seed_nodes": ["node1:9090", "node2:9090"],
    "join_token": "my-secret-cluster-token"
  },
  "log": {
    "level": "info",
    "format": "json"
  },
  "database": {
    "driver": "postgres",
    "url": "postgres://user:pass@host:5432/muxcore"
  },
  "cache": {
    "driver": "redis",
    "url": "redis://host:6379"
  },
  "audit": {
    "path": "/var/log/muxcore/audit.jsonl"
  },
  "modules": {
    "downloader-qbittorrent": {
      "qbittorrent_url": "http://localhost:8080",
      "poll_interval_seconds": 30
    }
  }
}

---

Environment Variables

All environment variables override their corresponding config file keys. Variables take highest precedence.

Server

Variable	Config Key	Default
MUXCORE_CONFIG	(config path)	muxcore.json
MUXCORE_ADDR	server.addr	:8080
MUXCORE_TLS_CERT	server.cert_file	""
MUXCORE_TLS_KEY	server.key_file	""

gRPC

Variable	Config Key	Default
MUXCORE_GRPC_TLS_CERT	grpc.cert_file	""
MUXCORE_GRPC_TLS_KEY	grpc.key_file	""
MUXCORE_GRPC_MTLS_ENABLED	grpc.mtls_enabled	false
MUXCORE_GRPC_MTLS_CA	grpc.ca_cert_file	""
MUXCORE_GRPC_SEED_NODES	grpc.seed_nodes	"" (comma-separated)
MUXCORE_CLUSTER_JOIN_TOKEN	grpc.join_token	""
MUXCORE_INSECURE_DISABLE_TLS	(behavior flag)	unset

Logging

Variable	Config Key	Default
MUXCORE_LOG_LEVEL	log.level	info
MUXCORE_LOG_FORMAT	log.format	text

Database & Cache

Variable	Config Key	Default
MUXCORE_DATABASE_DRIVER	database.driver	""
MUXCORE_DATABASE_URL	database.url	""
MUXCORE_CACHE_DRIVER	cache.driver	""
MUXCORE_CACHE_URL	cache.url	""

Audit

Variable	Config Key	Default
MUXCORE_AUDIT_PATH	audit.path	"" (disabled)

Module Policy

Variable	Purpose	Default
MUXCORE_STRICT_CALL_POLICY	Hard-deny capability-mismatched mesh calls	false (soft-warn)
MUXCORE_STRICT_PUBLISH_POLICY	Hard-deny capability-mismatched event publishes	false (soft-warn)

Event Bus

Variable	Purpose	Default
MUXCORE_EVENT_JOURNAL_PATH	Directory for event WAL (write-ahead log). Enables persistence and SubscribeFrom replay.	"" (disabled)
MUXCORE_EVENT_REPLAY	Replay WAL events to late subscribers on startup	true

gRPC Rate Limiting

Variable	Purpose	Default
MUXCORE_GRPC_RATE_LIMIT	Max gRPC requests per minute per client IP	1000
MUXCORE_GRPC_REQUIRE_DISCOVERY_AUTH	Require authenticated caller for Discovery Watch/Members/Find*	false (open)
MUXCORE_GRPC_REQUIRE_EVENTS_AUTH	Require authenticated caller for Event Publish/Subscribe	false (open)

Debug & Observability

Variable	Purpose	Default
MUXCORE_DEBUG_ENABLE	Enable pprof endpoints at /debug/pprof/	false
MUXCORE_METRICS_ENABLE	Enable Prometheus metrics at /metrics	false

Security (Insecure Dev Mode)

Variable	Purpose	Default
MUXCORE_INSECURE_DISABLE_TLS	Bypass TLS requirement for HTTP and gRPC	unset (TLS required)

---

CLI Flags

Flag	Default	Description
--tag	(none)	Tag name to load from spool (e.g., default)
--spool	https://github.com/Muxcore-Media/spool	Spool URL to fetch tags from
--version	—	Print version and exit

Without --tag, core starts as a bare loom — HTTP server + gRPC mesh, zero modules.

---

Config Hot-Reload (SIGHUP)

Send SIGHUP to apply config file changes at runtime:

kill -HUP $(pidof muxcored)

Applied live (no restart needed):

• log.level, log.format
• grpc.seed_nodes

Requires restart (warning logged, change NOT applied):

• audit.path — the file handle stays open to the original file until restart
• server.addr, grpc.addr
• Any TLS cert/key files
• database, cache settings
• grpc.join_token

---

TLS Configuration

Development Mode (No TLS)

Set MUXCORE_INSECURE_DISABLE_TLS=true to bypass TLS requirement for both HTTP and gRPC. The server logs a warning. Only use for local development.

MUXCORE_INSECURE_DISABLE_TLS=true muxcored --tag default

Production TLS (Server)

export MUXCORE_TLS_CERT=/etc/ssl/server-cert.pem
export MUXCORE_TLS_KEY=/etc/ssl/server-key.pem

Production TLS (gRPC)

export MUXCORE_GRPC_TLS_CERT=/etc/ssl/grpc-cert.pem
export MUXCORE_GRPC_TLS_KEY=/etc/ssl/grpc-key.pem

Mutual TLS (mTLS)

export MUXCORE_GRPC_TLS_CERT=/etc/ssl/grpc-cert.pem
export MUXCORE_GRPC_TLS_KEY=/etc/ssl/grpc-key.pem
export MUXCORE_GRPC_MTLS_ENABLED=true
export MUXCORE_GRPC_MTLS_CA=/etc/ssl/ca.pem

---

Per-Module Configuration

The modules map in muxcore.json passes arbitrary configuration to individual modules by their module ID:

{
  "modules": {
    "downloader-qbittorrent": {
      "qbittorrent_url": "http://192.168.1.50:8080",
      "username": "admin",
      "poll_interval_seconds": 30
    },
    "transcoder-ffmpeg": {
      "gpu": "nvidia",
      "max_concurrent": 2
    }
  }
}

Modules read their config by looking up their own module ID in the Modules map. There is no environment variable equivalent — per-module config is file-only.