Storage

Choose in-memory operation or persist logs, counters, quotas, cooldowns, and key state with SQLite.

Storage modes

Mode	Behavior	Recommended for
In memory	State resets on restart; the recent-log buffer keeps the latest 200 entries.	Local development and temporary tests.
SQLite	Persists operational state and request history in one embedded database.	Long-running single-instance deployments.

Enable SQLite

config.yaml

storage:
  type: sqlite
  path: ~/.local/share/modelmux/modelmux.db

The schema is migrated automatically at startup. SQLite is opened in WAL mode for safer concurrent reads and writes inside the process.

Persisted data

Key status, usage, cooldown timers, and runtime state.
Daily request and token counters used by configured quotas.
Request logs with group, model, provider, key, status, latency, tokens, and timestamp.
Data queried by modelmux logs and the /logs endpoint.
Metrics source data derived from stored request history.

Database and secret files

Default data directory

~/.local/share/modelmux/modelmux.db
~/.local/share/modelmux/modelmux.db-wal
~/.local/share/modelmux/modelmux.db-shm
~/.local/share/modelmux/secrets.enc

The -wal and -shm files are normal SQLite WAL files. Do not delete them while ModelMux is running.

Backup and restore

Stop ModelMux or use a consistent SQLite backup method before copying a live database. A simple stopped-service backup is:

Terminal

cp ~/.local/share/modelmux/modelmux.db ~/modelmux.db.backup
cp ~/.local/share/modelmux/secrets.enc ~/modelmux-secrets.enc.backup

Keep the master key

A copied secrets.enc file cannot be decrypted without the matching MODELMUX_MASTER_KEY.

Deployment constraints

SQLite storage is designed for one ModelMux process using one database file. Do not share the same SQLite path across several running ModelMux instances or network-mounted replicas.

For container deployment, mount the data directory on persistent storage. Ensure the process user can create the database, WAL files, and encrypted secret file.