Configuration

Contenox stores all configuration in a single SQLite database at ~/.contenox/local.db. There is no YAML file — register backends and set defaults using CLI commands.

Workspaces vs global

Contenox has two layers of state:

Global state — one shared database at ~/.contenox/local.db. Holds backends, provider configuration, and global defaults. Shared by every project on your machine.
Workspace state — one .contenox/ directory per project, containing a workspace.id file (a UUID written on contenox init) and that workspace's chain files. Each workspace scopes its own sessions, messages, and workspace-specific config overrides inside the single global database.

Running contenox init in a project directory creates a .contenox/ folder with a fresh workspace.id and the default chain files. The same project always resolves to the same workspace regardless of where you invoke contenox from, as long as you're inside the directory tree.

Backends and global defaults survive across every workspace. A workspace's sessions and workspace-scoped overrides are invisible to other workspaces.

Register a backend

# Local Ollama (base URL inferred automatically)
contenox backend add ollama --type ollama

# Ollama Cloud
contenox backend add ollama-cloud --type ollama --url https://ollama.com/api --api-key-env OLLAMA_API_KEY

# OpenAI (base URL inferred)
contenox backend add openai --type openai --api-key-env OPENAI_API_KEY

# Google Gemini
contenox backend add gemini --type gemini --api-key-env GEMINI_API_KEY

# Self-hosted vLLM or compatible endpoint
contenox backend add myvllm --type vllm --url http://gpu-host:8000

# Embedded llama.cpp inference — no server, no network, no API key
contenox backend add embedded --type local --url <path-to-gguf-or-huggingface-url>

# Vertex AI — --url is required (include project and region)
# Option A: service account JSON (works everywhere)
export VERTEX_SA_JSON=$(cat /path/to/service-account.json)
contenox backend add vertex --type vertex-google \
  --url "https://us-central1-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1" \
  --api-key-env VERTEX_SA_JSON

# Option B: Application Default Credentials (CLI only)
gcloud auth application-default login
gcloud auth application-default set-quota-project YOUR_PROJECT_ID
contenox backend add vertex --type vertex-google \
  --url "https://us-central1-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1"

Backends are global — they live in ~/.contenox/local.db and are visible to every workspace.

Set persistent defaults

contenox config set default-model    qwen2.5:7b
contenox config set default-provider ollama
contenox config set default-chain    .contenox/default-chain.json
contenox config set hitl-policy-name hitl-policy-strict.json

contenox config list   # review current settings and their scope

Key	Scope	Description
`default-model`	global	Model name used when `--model` is not passed
`default-provider`	global	Provider type used when `--provider` is not passed
`default-chain`	workspace	Chain file used in this workspace; falls back to the global value when unset
`hitl-policy-name`	workspace	Active HITL policy for this workspace; falls back to the global value when unset

contenox config list shows each key's current value and its scope (global / workspace) so you can see whether a setting is inherited or overridden locally.

Manage backends

contenox backend list
contenox backend show openai
contenox backend remove myvllm

Supported providers

`--type`	Notes
`local`	Embedded llama.cpp inference compiled into the contenox binary. No external server. `--url` takes a GGUF path or a huggingface.co URL.
`ollama`	Local: run `ollama serve` first. Hosted: use `--url https://ollama.com/api --api-key-env OLLAMA_API_KEY`.
`openai`	Use `--api-key-env OPENAI_API_KEY`. Base URL inferred.
`gemini`	Use `--api-key-env GEMINI_API_KEY`. Base URL inferred.
`vllm`	Self-hosted OpenAI-compatible endpoint. Requires `--url`.
`vertex-google`	Vertex AI — Google models (Gemini). Requires `--url` with project and region. Auth: service account JSON via `--api-key-env`, or ADC (no flag needed if `gcloud auth application-default login` is configured).
`vertex-anthropic`	Vertex AI — Anthropic models (Claude). Same auth and URL pattern as `vertex-google`.
`vertex-meta`	Vertex AI — Meta models (Llama). Same auth and URL pattern as `vertex-google`.
`vertex-mistralai`	Vertex AI — Mistral models. Same auth and URL pattern as `vertex-google`.

Database location

Contenox uses one database at ~/.contenox/local.db by default. Override with:

--db <path> — use a specific SQLite file (useful for isolated tests or per-environment state)
--data-dir <path> — point at a specific workspace directory (overrides the walk-up discovery)

The walk-up from the current directory only decides which workspace you're operating in (by finding a .contenox/workspace.id file). The database itself is always the global one unless --db is passed.