Configuration Reference

Environment Variables

These variables are set in your .env file and read by Docker Compose.

Internal Environment Variables

These are set inside the compose files and should not be changed in .env. They configure the gateway container's internal behavior.

Application Settings

These keys are set in config/appsettings.user.json inside the data directory. Each can also be set as an environment variable by replacing : with __ (e.g. SOPHON__Plugins__Enabled=true).

Voice

Host-wide tunables for the speech engine, under Sophon:Voice. These are operator settings: everything a user controls (language, speech speed, input and output mode, conversation mode, endpointing, max utterance) is a per-user preference in Voice Center, not a config key. See Voice Settings.

Sophon:Voice:BargeInMinWords exists in the configuration shape but is reserved — nothing reads it. There is no automatic speech-triggered barge-in in this release; interrupting is a mic press. See Voice Limits.

Data Directory Layout

All Sophon runtime state lives in SOPHON_DATA on the host (mounted at /home/sophon/.sophon inside the container):

~/.sophon/
├── config/
│   ├── appsettings.user.json     # User-level configuration overrides
│   ├── models.json               # LLM provider configs (API keys encrypted)
│   ├── channels.json             # Channel connections (encrypted)
│   ├── tts.json                  # Text-to-speech provider list (non-secret)
│   └── stt.json                  # Speech-to-text providers + host listening defaults
├── agents/
│   └── default/
│       ├── SOUL.md               # Agent personality
│       ├── BOOT.md               # First-run init script
│       ├── HEARTBEAT.md          # Heartbeat checklist
│       └── TOOLS.md              # Available tools config
├── skills/
│   ├── bundled/                  # Ships with Sophon (read-only)
│   ├── installed/                # From Marketplace
│   └── self-authored/            # Created by the agent
├── memory/
│   ├── daily/                    # Short-term daily logs
│   ├── MEMORY.md                 # Long-term curated facts
│   └── entities/                 # Structured entity store
├── documents/
│   ├── uploads/                  # User-uploaded files
│   ├── processed/                # Extracted text and embeddings
│   └── index/                    # Search index (FTS + vector)
├── cron/
│   └── jobs.json                 # Scheduled jobs
├── workflows/
│   └── *.json                    # Workflow definitions
├── sandbox/
│   └── workspaces/               # Ephemeral code execution (auto-cleaned)
├── security/
│   └── vault.key                 # AES-256 encryption key — CRITICAL, back up!
├── logs/
│   └── sophon-YYYYMMDD.log       # Application logs (rotated daily)
└── data/
    ├── sophon.db                 # SQLite database (Personal tier only)
    └── cache/                    # Local cache (thumbnails, embeddings)

The security/vault.key file is the AES-256 encryption key used to encrypt credentials at rest. Without this file, encrypted credentials cannot be decrypted. Always include it in backups.

tts.json and stt.json hold non-secret configuration only — the provider id, display name, provider type, endpoint or region, voice id, priority and last health status. Provider API keys live in the credential vault; each entry stores a credential id, not a key. stt.json also carries the host-wide listening defaults that a user's personal overrides fall back to.

Tier Behavior

Changing tiers is a configuration change — the same binary, different feature flags. Set SOPHON__Tier in your compose file to switch.

First-Run Behavior

On first startup, Sophon:

1. Creates the data directory if SOPHON_DATA doesn't exist on the host
2. Seeds the default agent — creates agents/default/SOUL.md with a starter personality
3. Runs database migrations — creates the SQLite database (Personal) or migrates PostgreSQL (Pro/Enterprise)
4. Generates vault.key — creates the encryption key for credential storage
5. Enters Setup Mode — the Dashboard shows the Setup Wizard to configure your first LLM provider

No manual migration step is ever needed. EF Core migrations run automatically on startup.