Configuration

Dynoxide is configured entirely through CLI flags and environment variables. No config files.

Storage

By default, Dynoxide runs in-memory. Everything disappears when the process stops. For persistent storage, pass a file path:

dynoxide --db-path data.db

The file is a standard SQLite database. You can inspect it with any SQLite tool.

Upgrading a database file

Product 1.3.0 upgrades a database to schema version 11 when it opens it. This changes what 1.2.x reads in two cases:

• A GSI with more than one partition key attribute or more than one sort key attribute. Its index entries are rebuilt.
• A table with a vector index. Its stored item sizes are recomputed.

If your file has either and you may return to 1.2.x, keep a copy before upgrading. 1.2.x doesn't check schema versions and would read those indexes or sizes wrongly. Files without either feature still read correctly in 1.2.x after opening in 1.3.0. The same distinction applies to encrypted files and browser OPFS databases.

From 1.3.0, a file written by a newer, unsupported schema is refused with an error naming its version and the newest this build can read. The file is left unchanged. The browser build applies the same checks to OPFS databases.

Opening a file waits up to 30 seconds for another process's lock, allowing a second process to wait for an upgrade already in progress. Once open, requests retain the five-second lock wait.

Restoring snapshots

From 1.3.0, restoring an older snapshot migrates a private copy before replacing the current database. A failed restore leaves the current database as it was. A missing path, an empty file, another application's database or a snapshot with a newer, unsupported schema is refused.

Database::restore_from opens the source read-only, though a WAL-mode snapshot may leave -wal and -shm files beside it. Backup and restore retry a busy database for five seconds (plus at most one SQLite busy wait), and give up after 50 restarts if other connections keep changing the data being copied. See MCP snapshots for the agent tools.

Pre-creating tables

--schema takes a DescribeTable JSON file and creates each table in it on startup, skipping any that already exist. It works on both the bare form and serve, and gets an empty database into the right shape without an import:

aws dynamodb describe-table --table-name Users > schema.json
dynoxide --schema schema.json --db-path dev.db

Encryption

Dynoxide supports at-rest encryption via SQLCipher. You'll need the encrypted build:

cargo install dynoxide-rs --no-default-features --features encrypted-full

Then provide a key (64-character hex string):

openssl rand -hex 32 > key.hex
dynoxide --db-path data.db --encryption-key-file key.hex

Or via environment variable:

DYNOXIDE_ENCRYPTION_KEY=$(cat key.hex) dynoxide --db-path data.db

Network

To listen on all interfaces (useful in Docker or CI):

dynoxide --host 0.0.0.0

Logging

From 1.3.0, --log quiet suppresses informational startup and shutdown messages on stderr:

dynoxide --log quiet
dynoxide mcp --log quiet

Warnings, errors and the first-run MCP token message still print. Import serving modes accept it too, and still print the import report. On import, it conflicts with --output. The CLI reference covers each form and readiness checks.

MCP co-hosting

You can run the HTTP server and MCP server together:

dynoxide --mcp
dynoxide --mcp --mcp-port 19280 --mcp-read-only

The MCP server shares the same database instance as the HTTP server.

Data model (OneTable)

If you're using a single-table design, pass a OneTable schema to give the MCP server context about your entities:

dynoxide mcp --data-model schema.json

This doesn't affect how Dynoxide stores or validates data - it's purely informational context for the agent. The schema tells the agent things like entity names, key templates, and which GSI maps to which entity.

Every flag on every subcommand is in the CLI reference, or run dynoxide --help.