Configuration

The host is configured via a YAML file passed with the -config flag. Environment variables and .env files are supported for secrets and environment-specific values.

Environment variable substitution

The config file supports environment variable expansion before YAML parsing:

Syntax	Behavior
${VAR}	Replaced with the value of VAR. Empty string if unset.
${VAR:-default}	Uses default if VAR is unset or empty.
${VAR-default}	Uses default only if VAR is unset (empty string is kept).
${VAR:?error message}	Fails with the error message if VAR is unset or empty.
${VAR?error message}	Fails with the error message if VAR is unset.

Example:

http:
  addr: "${HTTP_ADDR:-:8080}"
  auth:
    tokens:
      - "${AUTH_TOKEN:?AUTH_TOKEN must be set}"

.env file loading

The host automatically loads environment variables from .env files located in the same directory as the config file:

1. .env — base environment
2. .env.local — local overrides (typically gitignored)

Later files override earlier ones.

Minimal configuration

http:
  addr: ":8080"

skills:
  - skills/echo.yaml

This starts the MCP server on port 8080 with a single skill. All other settings use defaults.

Complete example

# ── HTTP server ────────────────────────────────────────
http:
  addr: "${HTTP_ADDR:-:8080}"
  server_url: "https://your-domain.com"
  auth:
    tokens:
      - "${AUTH_TOKEN}"

# ── Runtime ────────────────────────────────────────────
runtime:
  cache_dir: "/var/luminarys/cache"
  memory_limit_mb: 64

# ── Database ───────────────────────────────────────────
db:
  path: "/var/luminarys/data/state.db"

# ── Logging ────────────────────────────────────────────
log:
  level: "info"
  stderr: true
  skill_log: false
  file:
    enabled: true
    path: "/var/log/luminarys/host.log"
    max_size_mb: 100
    max_backups: 3

# ── Tracing ────────────────────────────────────────────
tracing:
  enabled: true

# ── Skills ─────────────────────────────────────────────
skills:
  - config/skills/echo.yaml
  - config/skills/fs.yaml
  - config/skills/web.yaml

# ── Cluster (optional) ────────────────────────────────
cluster:
  enabled: true
  cluster_id: "my-cluster"
  node_id: "master"
  role: "master"
  nats_url: "nats://nats:4222"
  relay_port: 4223
  file_transfer:
    allowed_nodes: ["*"]
    local_dirs: ["/data:rw"]
  auth:
    token: "${NATS_TOKEN}"

Config reference

http

Controls the HTTP server for MCP and REST endpoints.

Field	Type	Default	Description
addr	string	:8080	Listen address (e.g., :8080, 0.0.0.0:9090)
server_url	string	—	Public URL for MCP endpoint discovery. Set when behind a reverse proxy.
auth.tokens	list	[]	Bearer tokens for authentication. Empty = no auth required.

When auth.tokens is configured, all MCP and REST endpoints require an Authorization: Bearer <token> header.

runtime

Controls the skill execution engine.

Field	Type	Default	Description
cache_dir	string	~/.luminarys/cache	Directory for compiled module cache. Speeds up subsequent starts.
memory_limit_mb	int	0 (unlimited)	Max linear memory per skill in MB. Recommended: 64 for production.

db

Embedded database for skill state persistence.

Field	Type	Default	Description
path	string	~/.luminarys/data/state.db	Path to the database file

log

Field	Type	Default	Description
level	string	info	Log level: debug, info, warn, error
stderr	bool	true	Write logs to stderr
skill_log	bool	false	Forward skill log_write calls to host log
file.enabled	bool	false	Enable file logging
file.path	string	~/.luminarys/logs/host.log	Log file path
file.max_size_mb	int	100	Rotate log file at this size (MB)
file.max_backups	int	3	Number of rotated files to keep

tracing

Field	Type	Default	Description
enabled	bool	false	Enable request tracing (toggle at runtime via POST /admin/trace)

skills

A list of paths to skill manifest files. Paths are relative to the config file's directory.

skills:
  - config/skills/echo.yaml
  - config/skills/fs.yaml
  - /opt/luminarys/skills/custom.yaml

Each manifest defines the skill's identity, binary path, permissions, and MCP mapping. See the Manifest reference for details.

cluster

Enables multi-node clustering via NATS.

Field	Type	Default	Description
enabled	bool	false	Enable clustering
cluster_id	string	—	Cluster identifier (must match across all nodes)
node_id	string	random	Stable node identifier (used in file transfer paths)
role	string	—	master or slave
nats_url	string	—	NATS server URL
relay_port	int	4223	File transfer relay port on the NATS server host
remote_invoke_timeout	duration	30s	Timeout for cross-node skill calls
heartbeat_interval	duration	5s	How often nodes send heartbeats
node_ttl	duration	15s	Remove node from registry after this silence
connect_timeout	duration	10s	How long slave waits for master on connect
file_transfer.allowed_nodes	list	[]	Nodes allowed for file transfers (["*"] = all)
file_transfer.local_dirs	list	[]	Local directories accessible for transfers (e.g., ["/data:rw"])
auth.token	string	—	NATS authentication token
tls.enabled	bool	false	Enable TLS for NATS connection
tls.ca_file	string	—	CA certificate for server verification
tls.cert_file	string	—	Client certificate (mTLS)
tls.key_file	string	—	Client key (mTLS)
tls.insecure	bool	false	Skip server certificate verification (dev only)

See Clustering for architecture details and deployment examples.

Validate configuration

Run the validator before deploying:

luminarys -validate -config config/host.yaml

Checks: config syntax, manifest validity, skill binary paths, duplicate IDs, cluster consistency.

Default paths

When fields are omitted, the host uses paths under ~/.luminarys/:

Purpose	Default path
Database	~/.luminarys/data/state.db
Module cache	~/.luminarys/cache/
Log file	~/.luminarys/logs/host.log