Configuration
How Stella is configured — settings.json, credentials, workspace files, and the scope hierarchy.
Stella reads configuration from a few well-defined places. Most users need only an API
key; teams and power users reach for settings.json.
What lives where
| Path | Purpose |
|---|---|
~/.config/stella/settings.json | User-scope settings: provider overrides, hooks |
<workspace>/.stella/settings.json | Project-scope settings (highest precedence) |
org-managed settings.json | Organization defaults (see below) |
~/.config/stella/credentials.toml | Stored API keys |
<workspace>/.stella/mcp.toml | MCP servers to connect at session start |
<workspace>/.stella/tools/*.toml | Custom script tools |
<workspace>/.stella/domains.toml | Domain taxonomy (from stella init) |
<workspace>/.stella/memories/*.md | Saved workspace memories |
<workspace>/.stella/store.db | Local telemetry & store — embedded SQLite |
The settings hierarchy
settings.json is read across three scopes and merged field by field, with the more
specific scope winning:
- project —
<workspace>/.stella/settings.json(highest preference) - org-managed — a system-level managed file (middle)
- user —
~/.config/stella/settings.json(lowest preference)
A project entry overrides an org-managed one, which overrides a user one — per field, so a project can change just a base URL while inheriting an API key from a higher scope. This is the same layering the rest of Stella's settings use.
See settings.json for the full schema, the org-managed path, and worked examples.
Configuration vs. credentials
Two separate concerns:
- settings.json configures behavior — which base URL a provider uses, its display name, default model, and lifecycle hooks. It may also carry an API key.
- credentials.toml stores only API keys, written with owner-only permissions.
Both feed the credential chain.
Everything you can configure
Stella is configured through three kinds of surface — files, environment variables, and command-line flags — with flags winning over env vars winning over files. This table is the complete map; each row links to its detail page.
| What you want to set | Surface | Example |
|---|---|---|
| Which provider/model runs | --model flag · STELLA_MODEL · providers.<id>.default_model | stella --model anthropic/claude-fable-5 run "…" |
| A provider's API key | --api-key flag · provider env var · settings.json api_key · credentials.toml | export ANTHROPIC_API_KEY=… |
| A provider's base URL | --base-url flag · STELLA_BASE_URL · providers.<id>.base_url | providers.zai.base_url → coding endpoint |
| A provider's display name | settings.json providers.<id>.name | see settings.json |
| Output format (text/json/stream-json) | --output-format flag · STELLA_OUTPUT_FORMAT | stella --output-format json run "…" |
| A hard USD spend cap | --budget flag · STELLA_BUDGET | stella --budget 2.00 goal "…" |
| Shell commands on lifecycle events | settings.json hooks key | Hooks |
| Per-agent engine models (worker/judge/triage) | settings.json agent_engine_config | Agent engine config |
Enable the raw bash tool (off by default) | settings.json tools.bash: "on" | settings.json |
| Org-managed defaults for a fleet | STELLA_MANAGED_SETTINGS → a settings.json | settings hierarchy |
| Trust a repo's project-scope hooks & routing | STELLA_TRUST_PROJECT=1 | trust boundary |
| MCP servers to connect | <workspace>/.stella/mcp.toml | MCP |
| Custom script tools | <workspace>/.stella/tools/*.toml | Custom tools |
| Per-tool permission gates | hooks PreToolUse matchers + the tools switches | Permissions |
| Force the plain REPL (no TUI) | --plain flag · STELLA_PLAIN=1 | stella --plain chat |
| Freeze TUI animation (CI/recordings) | --no-anim flag · STELLA_NO_ANIM · NO_COLOR | stella --no-anim chat |
Stella auto-detects the provider from whichever API keys are present in your
environment — the minimum viable configuration is a single *_API_KEY env var and nothing
else. Everything above is for when you want to override that default behavior.
Common tasks
Point a Z.ai coding-plan subscription at its endpoint (user scope — a subscription is
personal, and project scope would need STELLA_TRUST_PROJECT=1):
{ "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_BUDGET=5 \
stella --output-format json run "port the utils module to the new API"Ship org-wide defaults every project inherits (a gateway URL + team key), leaving projects free to override per field:
export STELLA_MANAGED_SETTINGS=/etc/stella/settings.jsonRun against a local OpenAI-compatible server (Ollama, vLLM, LM Studio):
stella --model local/llama3.1 --base-url http://localhost:11434/v1 run "…"Gate every bash call through a guard script (settings.json):
{ "hooks": { "PreToolUse": [ { "matcher": "bash",
"hooks": [ { "command": "./scripts/guard.sh", "timeoutMs": 5000 } ] } ] } }Inspecting the resolved 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