Configuration · CommonOS

Files

~/.commonos

commonos.toml          which plugins run, and their settings
pricing.toml           CommonBill prices (optional)
profiles/<name>/       one folder per profile; see Profiles

Every file is optional. With none of them, cos runs every installed plugin with default settings, and only the mock model has a price.

Environment variables

Variable	Default	Does
`COMMONOS_HOME`	`~/.commonos`	Where profiles and config files live
`COMMONOS_DATABASE_URL`	`postgres:///commonos`	The shared database. Same as `--database-url`.
`COMMONOS_PROVIDER`	unset	`mock` runs every profile on the mock model. Same as `--mock`.
`ANTHROPIC_API_KEY`	unset	Used by profiles without a key in their own `.env`
`RUST_LOG`	`info,sqlx=warn`	Log filter, e.g. `debug` or `warn`
`COMMONOS_TEST_DATABASE_URL`	unset	The database for the test suite. Database tests skip without it.

commonos.toml

~/.commonos/commonos.toml

[plugins]
# Which plugins run, in order. Default: every installed plugin.
enabled = ["bill", "memory", "delegate"]

[plugins.delegate]
max_spawn_depth = 1
max_concurrent_children = 10
model = "<model id>"

Key	Meaning
`plugins.enabled`	Plugin ids to run, in order. Order sets hook order.
`plugins.<id>`	That plugin’s settings. See each plugin’s page.

An id in enabled that isn’t installed stops start-up and lists the installed ids.

pricing.toml

US dollars per million tokens, per model id. Read by CommonBill.

~/.commonos/pricing.toml

[models."<model id>"]
input_per_mtok = 0.0
output_per_mtok = 0.0
cache_read_per_mtok = 0.0   # optional, default 0
cache_write_per_mtok = 0.0  # optional, default 0

Profile files

File	Holds	Details
`config.toml`	`provider`, `model`, `tags`, `tools`, `max_iterations`	Profiles
`.env`	API keys	Profiles
`SOUL.md`	The persona	Prompt Tiers
`skills/*/SKILL.md`	Skills	Profiles

Command-line flags

Flag	Default	Applies to
`-p, --profile <name>`	—	`cos chat`
`--database-url <url>`	`postgres:///commonos`	every command
`--mock`	off	every command
`--port <port>`	`9120`	`cos serve`
`--approval-timeout <seconds>`	`300`	`cos serve`

When to restart: cos reads profiles, commonos.toml and pricing.toml at start-up. Edits take effect after a restart. SOUL.md and skills changes also apply only to new sessions.