Configuration

Makaio has separate configuration paths for runtime discovery, bootstrap settings, and the SQLite database. They intentionally do not share one global precedence chain.

Runtime Config Files

Runtime config files (makaio.config.ts, makaio.config.js, or makaio.config.json) control extension discovery, launcher command defaults, and package configuration defaults.

Lookup order:

1. An explicit CLI/programmatic config path, such as root-level --config
2. MAKAIO_CONFIG_FILE
3. $MAKAIO_HOME/makaio.config.ts
4. $MAKAIO_HOME/makaio.config.js
5. $MAKAIO_HOME/makaio.config.json
6. Built-in defaults

Relative discovery paths inside the config file resolve from the config file directory. When no config file is selected, default installed-extension roots resolve under MAKAIO_HOME.

Environment Variables

Variable	Purpose	Default	Notes
MAKAIO_HOME	Runtime data home for config lookup, installed extensions, machine identity, and the default database path	~/.makaio	Blank values are ignored.
MAKAIO_CONFIG_FILE	Runtime config file override	none	Used when no explicit --config or programmatic config path was passed.
MAKAIO_MODE	Bootstrap runtime mode	local	Valid values: local, remote, hybrid.
MAKAIO_BUS_URL	Remote bus URL for clients/bootstrap config	ws://127.0.0.1:6252/bus for CLI clients	Use ws:// or wss://.
MAKAIO_BUS_SECRET	HMAC bus secret	none	makaio serve uses it to require authenticated bus clients; CLI clients use it when /health reports auth: true. In ConfigProvider, a bus secret also requires MAKAIO_BUS_URL.
MAKAIO_RELAY_URL	Relay server WebSocket URL	none	Also maps to the relay.url bootstrap config field.
MAKAIO_DATABASE_PATH	SQLite database file override	$MAKAIO_HOME/makaio.db	Database-specific; see the precedence below.

Bootstrap config handled by ConfigProvider merges in this order:

1. Default config
2. Stored config
3. Environment variables
4. Programmatic overrides

Database Path

The database path is resolved by the Node database initializer, not by runtime config file precedence:

1. Programmatic dbPath
2. MAKAIO_DATABASE_PATH
3. $MAKAIO_HOME/makaio.db

Use MAKAIO_DATABASE_PATH for isolated test databases or when the SQLite file must live outside the runtime data home.

MAKAIO_DATABASE_PATH=/tmp/e2e-test.db makaio serve --port 0

Relay

Use MAKAIO_RELAY_URL to connect to a remote Makaio relay server for browser-to-machine communication. If neither the environment variable nor a bootstrap config value exists, relay connection is disabled.

MAKAIO_RELAY_URL=wss://relay.example.com makaio

Desktop Apps

Desktop host configuration lives under ../apps/electron/ and ../apps/electrobun/ from this document. Notable paths:

Purpose	Path
Electron main-process runtime boot	../apps/electron/src/main/main.ts
Electrobun main-process runtime boot	../apps/electrobun/src/main/main.ts
Electron renderer bus URL build-time config	../apps/electron/vite.renderer.config.ts
Electrobun renderer bus URL build-time config	../apps/electrobun/vite.renderer.config.ts
Electron E2E environment overrides	../apps/electron/e2e/playwright.config.ts