Configuration Reference

Complete reference for environment variables, internal configuration, data directory layout, and tier behavior.

Environment Variables

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

Variable	Default	Tiers	Description
`SOPHON_DATA`	required	All	Absolute path to host data directory. No `~` expansion — use full path. Forward slashes on Windows.
`DOCKER_GID`	`999`	All (Linux)	Docker socket group ID. Find with `getent group docker \| cut -d: -f3`
`GATEWAY_PORT`	`8081`	All	Host port for the Gateway API
`DASHBOARD_PORT`	`8080`	All	Host port for the Dashboard UI
`POSTGRES_USER`	`sophon`	Pro, Enterprise	PostgreSQL username
`POSTGRES_PASSWORD`	`sophon`	Pro, Enterprise	PostgreSQL password — change in production
`POSTGRES_PORT`	`5432`	Pro, Enterprise	Host port for PostgreSQL
`QDRANT_HTTP_PORT`	`6333`	Pro, Enterprise	Host port for Qdrant HTTP API
`QDRANT_GRPC_PORT`	`6334`	Pro, Enterprise	Host port for Qdrant gRPC
`REDIS_PORT`	`6379`	Enterprise	Host port for Redis
`REDIS_PASSWORD`	`sophon`	Enterprise	Redis password — change in production
`RABBITMQ_USER`	`sophon`	Enterprise	RabbitMQ username
`RABBITMQ_PASSWORD`	`sophon`	Enterprise	RabbitMQ password — change in production
`RABBITMQ_PORT`	`5672`	Enterprise	Host port for RabbitMQ AMQP
`RABBITMQ_MGMT_PORT`	`15672`	Enterprise	Host port for RabbitMQ management UI
`VAULT_PROVIDER`	`local`	Enterprise	Credential vault backend (`local`, `hashicorp`, `aws`, `azure`)
`VAULT_ADDRESS`	`http://vault:8200`	Enterprise	HashiCorp Vault address
`VAULT_TOKEN`	(empty)	Enterprise	HashiCorp Vault token
`JWT_SECRET`	(empty)	Enterprise	JWT signing secret for multi-user auth
`SSO_ENABLED`	`false`	Enterprise	Enable SSO/OIDC authentication

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.

Variable	Value	Description
`SOPHON__Tier`	`Personal` / `Pro` / `Enterprise`	Feature tier — controls which features are enabled
`SOPHON__Database`	`sqlite` / `postgresql`	Database backend. Personal uses SQLite; Pro/Enterprise use PostgreSQL.
`SOPHON__DataDirectory`	`/home/sophon/.sophon`	Container-internal path where the data volume is mounted
`SOPHON__Sandbox__HostWorkspacesPath`	`${SOPHON_DATA}/sandbox/workspaces`	Host path for sandbox bind mounts (must be accessible from the Docker daemon)
`ConnectionStrings__PostgreSQL`	`Host=postgres;...`	PostgreSQL connection string (Pro/Enterprise)
`Qdrant__Endpoint`	`http://qdrant:6334`	Qdrant gRPC endpoint (Pro/Enterprise)
`Sophon__Redis__ConnectionString`	`redis:6379,...`	Redis connection with password (Enterprise)
`Sophon__MessageBus__Provider`	`rabbitmq`	Message bus backend (Enterprise)
`SOPHON_GATEWAY_URL`	`http://sophon-gateway:8080`	Internal URL the Dashboard uses to reach the Gateway

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                  # TTS provider configs (encrypted)
├── 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.

Tier Behavior

Feature	Personal	Pro	Enterprise
Database	SQLite (embedded)	PostgreSQL 17	PostgreSQL 17
Authentication	Auto-admin (single user)	JWT multi-user	JWT + SSO/OIDC
Credential Encryption	AES-256 (vault.key)	AES-256 (vault.key)	External vault (HashiCorp/AWS/Azure)
Vector Store	(none)	Qdrant	Qdrant
Cache	In-memory	In-memory	Redis 7
Message Bus	In-process	In-process	RabbitMQ 4.0
Multi-Tenancy	(none)	(none)	Full tenant isolation
Audit Logging	(none)	(none)	Full audit trail
RBAC	(none)	Basic roles	Full RBAC + custom roles
Horizontal Scaling	Single instance	Single instance	Multiple replicas (K8s)

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:

Creates the data directory if SOPHON_DATA doesn't exist on the host
Seeds the default agent — creates agents/default/SOUL.md with a starter personality
Runs database migrations — creates the SQLite database (Personal) or migrates PostgreSQL (Pro/Enterprise)
Generates vault.key — creates the encryption key for credential storage
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.