Configuration

Magec uses two separate configuration layers. Understanding this split is important because they work differently and serve different purposes.

The two layers

Infrastructure is about how the server runs. Resources are about what the server does.

Think of it like this: config.yaml is the wiring of your house (ports, protocols, switches). store.json is the furniture and appliances inside (your agents, their tools, who can talk to them).

config.yaml — Infrastructure

This file is read once at startup. Changes require a server restart. It controls only the server process itself — nothing about agents, backends, or AI.

server:
  host: 0.0.0.0
  port: 8080          # User API + Voice UI
  adminPort: 8081     # Admin API + Admin UI
  # adminPassword: ${MAGEC_ADMIN_PASSWORD}

voice:
  ui:
    enabled: true     # Toggle Voice UI and voice routes
  # onnxLibraryPath: /usr/lib/libonnxruntime.so

log:
  level: info         # debug, info, warn, error
  format: console     # console, json

Server

Controls where the server listens. Magec runs two HTTP servers on separate ports — one for users (API, Voice UI, webhooks) and one for administration (Admin UI, management API).

Voice

Controls voice features at the server level. This is independent of per-agent voice settings — it’s a global switch.

Log

Environment variables

All values in config.yaml support ${VAR} syntax for environment variable substitution. This is useful for Docker deployments where you want to configure the server without modifying the file:

server:
  port: ${MAGEC_PORT:-8080}

log:
  level: ${LOG_LEVEL:-info}

data/store.json — Resources

This is Magec’s internal database. Every agent, backend, memory provider, MCP server, client, command, and flow is stored here. The server keeps it in memory for fast access and writes to disk on every change.

You should never edit this file by hand. Use the Admin UI at http://localhost:8081 or the Admin REST API. Both provide full CRUD for all resource types with validation, health checks, and immediate hot-reload.

What’s inside

Hot-reload

Changes made through the Admin UI or API take effect immediately — no server restart needed. When you update an agent’s prompt, add a new backend, or modify a flow, the change is persisted to store.json and the server picks it up in real time.

Environment variables in store.json

Like config.yaml, the store also supports ${VAR} substitution. This is particularly useful for keeping API keys and tokens out of the file:

{
  "apiKey": "${OPENAI_API_KEY}"
}

The installer uses this for cloud deployments, so your API keys come from environment variables rather than being stored in plain text.

For a more convenient way to manage sensitive values, see Secrets — they let you store API keys through the Admin UI and reference them with the same ${VAR} syntax.

Backup and restore

To back up your entire Magec configuration, copy data/store.json. To restore it, put it back and restart the server. That single file contains every resource you’ve configured.