Reference
Files and environment variables
Where 8gent keeps its settings, and every environment variable it reads, traced to the code on main.
Everything lives in ~/.8gent/ unless noted. EIGHT_DATA_DIR moves it.
| Path | What is in it | How to change it |
|---|
~/.8gent/providers.json | The active provider and model, and provider entries | /provider, /model, --provider, --model |
~/.8gent/settings.json | Voice, performance, per-tab models, provider URLs, theme options, agent names | /settings, or edit it |
~/.8gent/keys.env | API keys for hosted providers, KEY=value lines. Shell variables win over it | 8gent keys |
~/.8gent/user.json | Your profile from first run | /onboarding, /preferences, 8gent preferences set |
~/.8gent/permissions.json | Allow and deny patterns | Edit it. See Allow and deny rules |
~/.8gent/hooks.json | Hooks | Edit it. See Hooks |
~/.8gent/mcp.json | MCP servers | Edit it. See MCP |
~/.8gent/failover.json | Model failover chains | Edit it |
~/.8gent/config.json | Your /theme choice | /theme |
<project>/.8gent/config.json | Per-project settings, including vision | 8gent init, /vision |
~/.8gent/sessions/ | Saved conversations | /history, 8gent session |
~/.8gent/memory/ | Local memory (SQLite) | 8gent memory |
~/.8gent/runs/<runId>/ledger.jsonl | The record of each /goal run | Read only |
~/.8gent/models/decide/ | A System One judge GGUF, for use without Ollama | Put the file there |
~/.8gent/sounds/launch.mp3 | The launch tune | Replace the file |
Defaults, abridged:
{
"voice": {
"outputEnabled": true,
"ttsVoice": "Ava",
"perAgent": { "orchestrator": "Daniel", "engineer": "Karen", "qa": "Moira" }
},
"performance": { "mode": "auto", "introBanner": "auto" },
"models": {
"tabs": {
"orchestrator": { "provider": "ollama", "model": "qwen3.6:27b" },
"engineer": { "provider": "lmstudio", "model": "google/gemma-4-26b-a4b" },
"qa": { "provider": "apfel", "model": "apple-foundationmodel" }
}
},
"agents": { "names": { "orchestrator": "Orchestrator", "engineer": "Engineer", "qa": "QA" } }
}
| Variable | What it does | Default |
|---|
OLLAMA_HOST, OLLAMA_BASE_URL | Where Ollama is. A bare host gets port 11434 | http://localhost:11434 |
EIGHT_LOCAL_SERVER | llama-server to use llama-server and never contact Ollama | ollama |
LLAMA_SERVER_URL | Where llama-server is | http://127.0.0.1:8080 |
LMSTUDIO_BASE_URL | Where LM Studio is, for requests | http://localhost:1234/v1 |
LM_STUDIO_HOST | Where the first-run check looks for LM Studio | port 1234 |
APFEL_BASE_URL | Where the Apple Foundation bridge is | http://127.0.0.1:11435/v1 |
OPENROUTER_API_KEY | Enables OpenRouter | unset |
EIGHT_TEXT_TOOLS | 1 forces the text tool protocol for any provider, 0 forces native tool calls | text protocol for Ollama, LM Studio, llama-server |
| Variable | What it does | Default |
|---|
EIGHT_SYSTEM_ONE | 0 off outside Guarded, 1 strict everywhere | on |
EIGHT_S1_SHARED_JUDGE | 0 gives each process its own judge | on |
EIGHT_DECIDE_OLLAMA_HOST | Server that holds the shared judge | http://localhost:11434 |
EIGHT_S1_ALLOWLIST | 0 sends read-only commands to the judge too | on |
EIGHT_DECIDE_GGUF | A judge GGUF file to load in-process | unset |
EIGHT_DECIDE_MODEL | A specific judge model, used only if installed | unset |
| Variable | What it does |
|---|
NO_COLOR | No colour. See Accessibility and voice |
FORCE_COLOR | 0 colour off, 1 to 3 on, over NO_COLOR |
8GENT_NO_INTRO | 1: no splash |
8GENT_REDUCED_MOTION | 1: no motion anywhere |
8GENT_LITE | 1: lite performance mode, no splash. Same as performance.mode: "lite" |
| Variable | What it does | Default |
|---|
EIGHT_DATA_DIR | Where 8gent keeps its data | ~/.8gent |