Configuration

How stella is configured: settings.json, credentials, workspace files, and the scope hierarchy.

stella reads its configuration from a few places. Most people only need an API key. Teams and power users also reach for settings.json.

What lives where

~/.stella/settings.json

Your personal settings: provider overrides, hooks, tools, and the context block.

<workspace>/.stella/settings.json

Settings for this project. These win over every other scope, and this file is also a trust boundary.

<repo>/stella.toml

The same settings as settings.json, written in TOML so your comments survive edits. See stella.toml. Lives at the repository root, not under .stella/.

org-managed settings.json

Organization-wide defaults (see below). The only scope that can set authority or enterprise_telemetry.

~/.stella/credentials.toml

Stored API keys, written with owner-only permissions.

<workspace>/.stella/mcp.toml

MCP servers to connect at session start.

<workspace>/.stella/tools/*.toml

Custom script tools.

<workspace>/.stella/domains.toml

The domain list stella init builds for your project.

<workspace>/.stella/memories/*.md

Saved workspace memories.

<workspace>/.stella/rules/*.md

Promoted rules and guard rules. Also read from .claude/rules/ and ~/.stella/rules/.

<workspace>/.stella/private/store.db

Local telemetry & store, stored in SQLite on your machine.

The settings hierarchy

stella reads settings.json from three scopes and merges them field by field. The more specific scope wins:

project — <workspace>/.stella/settings.json (checked first)
org-managed — a file your organization manages (checked second)
user — ~/.stella/settings.json (checked last)

A project setting overrides an org-managed one. An org-managed setting overrides a user one. This happens field by field, so a project can set just a base URL and still inherit an API key from a higher scope. The rest of stella's settings follow this same layering.

See settings.json for the full schema: all ten top-level sections, the org-managed path, and worked examples. The same settings are also available as stella.toml, a format that keeps your comments. Run stella migrate config to convert an existing settings.json to TOML.

Configuration vs. credentials

settings.json configures behavior: which base URL a provider uses, its display name, default model, and lifecycle hooks. It can also hold an API key.
credentials.toml stores only API keys, written with owner-only permissions.

Both feed the credential chain.

Everything you can configure

You can configure stella three ways: files, environment variables, and command-line flags. Flags win over environment variables. Environment variables win over files. Each card below links to its own detail page.

Providers, models, and keys

Which provider/model runs

Flags beat the environment, which beats the file.

Surface: --model · STELLA_MODEL · providers.<id>.default_model
Example: stella --model anthropic/claude-fable-5 run …

A provider's API key

The first hit in the credential chain wins; nothing below it is read.

Surface: --api-key · provider env var · api_key · credentials.toml
Example: export ANTHROPIC_API_KEY=…

A provider's base URL

A coding-plan endpoint, a proxy, or a gateway.

Surface: --base-url · STELLA_BASE_URL · providers.<id>.base_url
Example: providers.zai.base_url

A provider's display name

What stella config and stella models print.

Surface: providers.<id>.name

Output and run options

Output format

text, json, or stream-json.

Surface: --output-format · STELLA_OUTPUT_FORMAT
Example: stella run --output-format json … (run/fleet only)

A hard USD spend cap

Enforced, not advisory: work stops cleanly once spend passes the cap.

Surface: --spend-limit · STELLA_SPEND_LIMIT
Example: stella --spend-limit 2.00 goal "…"

Force the plain REPL (no TUI)

For pipes, plain terminals, and recordings.

Surface: --plain · STELLA_PLAIN=1
Example: stella --plain chat

Freeze TUI animation

For CI logs and screen recordings.

Surface: --no-anim · STELLA_NO_ANIM · NO_COLOR
Example: stella --no-anim chat

Tools, hooks, and context

Shell commands on lifecycle events

SessionStart, PreToolUse, PostToolUse.

Surface: settings.json hooks

Per-agent engine models

Worker, verifier, and triage roles, each with its own model and sampling params.

Surface: settings.json agent_engine_config

Switch off a tool

Every tool ships on. The tools section is the one way to turn one off.

Surface: settings.json tools.task_assign: "off"

Switch off a whole family

Groups such as task, scratch, mcp, or custom. Or use "*" for everything.

Surface: settings.json tools.mcp: "off"

Per-tool permission gates

A script that can block any tool call before it runs.

Surface: hooks PreToolUse matchers + tools switches

The adaptive-context lifecycle

Settings for learning, governance, promotion, efficacy, and retention. Off by default.

Surface: settings.json context

Third-party context sources

CGP providers reached over stdio or HTTP. Each one must pass a conformance check and get your consent first.

Surface: settings.json context_providers

MCP servers to connect

Connected at session start.

Surface: <workspace>/.stella/mcp.toml

Custom script tools

Your own executables, described as tool manifests.

Surface: <workspace>/.stella/tools/*.toml

Fleet, trust, diagnostics

Org-managed defaults for a fleet

One file every project on the machine inherits.

Surface: STELLA_MANAGED_SETTINGS
Example: /etc/stella/settings.json

Trust a repo's project-scope file

Unlocks project hooks, credential routing, context providers, tool grants, replacement prompts, and workspace custom tools.

Surface: STELLA_TRUST_PROJECT=1

The Command Deck's debug log

Structured, owner-only, and off unless asked for.

Surface: STELLA_DEBUG=1
Writes: ~/.local/state/stella/logs/deck-<pid>.jsonl

OXAGEN_DEBUG and OXAGEN_MEDIA_LIVE also work as names for STELLA_DEBUG and STELLA_MEDIA_LIVE. If you set both the old and new name, the STELLA_ name wins.

stella detects your provider automatically from whichever API key is present in your environment. The smallest setup you need is one *_API_KEY environment variable. Everything above is for when you want to change that default.

Common tasks

Point a Z.ai coding-plan subscription at its endpoint. Set this in user scope, since a subscription is personal. Project scope needs STELLA_TRUST_PROJECT=1:

~/.stella/settings.json

{ "providers": { "zai": { "base_url": "https://api.z.ai/api/coding/paas/v4" } } }

Full walkthrough: the coding-plan recipe.

Pin a model and a hard budget for an unattended CI run:

STELLA_MODEL=anthropic/claude-fable-5 STELLA_SPEND_LIMIT=5 \
  stella run --output-format json "port the utils module to the new API"

Ship org-wide defaults every project inherits, such as a gateway URL and team key. Projects can still override any field:

export STELLA_MANAGED_SETTINGS=/etc/stella/settings.json

Run against a local OpenAI-compatible server, such as Ollama, vLLM, or LM Studio:

stella --model local/llama3.1 --base-url http://localhost:11434/v1 run "…"

Gate a tool call through a guard script, in settings.json:

~/.stella/settings.json

{ "hooks": { "PreToolUse": [ { "matcher": "mcp__github__push_files",
  "hooks": [ { "command": "./scripts/guard.sh", "timeoutMs": 5000 } ] } ] } }

Check your configuration

stella config    # the fully resolved provider, model, key preview, and base URL
stella models    # every provider with its effective base URL and key status

Configuration

On this page