Configuration & Model Providers

Scout is configured via environment variables in .env (see .env.example in the repository root).

Adding & Managing Model Providers

Scout uses the goose CLI under the hood and supports multiple AI model providers simultaneously:

1. Google Gemini (GOOGLE_API_KEY or GEMINI_API_KEY) — Always Required:
   • Even if you use another provider for chat or subagents, a Gemini API key is always required because Scout uses Gemini models for vector embeddings (conversational memory and knowledge base search), conversation compaction, and voice note transcription.
   • Use a pay-as-you-go key from Google AI Studio tied to a Google Cloud project with billing enabled. Using a free-tier AI Studio key with an external harness like Scout may violate Google’s terms of service, and free-tier rate limits (429) will interrupt agent loops and background reminders.
2. Optional Providers:
   • Set any combination of ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, XAI_API_KEY, or OLLAMA_HOST.
   • Each provider whose key is configured automatically appears in the Settings → Agent Profile page in the web UI.
   • From Agent Profile, you can enable multiple models across providers, pick your default baseline model, and rely on automatic model fallback (if the primary model fails with a provider error, Scout retries the turn in a fresh Goose session with the next enabled model).
   • Individual Subagents and Trading Agents can also override the default model with a specific provider:model choice.

Adding Provider Keys on a Google Cloud VM

When deploying or upgrading with ./deploy/deploy-vm.sh, pass the provider flags to add or rotate keys in /opt/scout/.env:

./deploy/deploy-vm.sh upgrade \
  --anthropic-api-key "sk-ant-..." \
  --openai-api-key "sk-..."

Keys you omit during upgrade are left unchanged on the VM.

---

.env Configuration Reference

Container Image & Domain

Variable	Default	Description
APP_IMAGE	ghcr.io/kcthota/scout:latest	Pre-built container image from GitHub Container Registry. Pin to a tag like ghcr.io/kcthota/scout:v0.1.0 if desired.
DOMAIN	agent.yourdomain.com	Public domain pointing to your server. Caddy automatically provisions a Let’s Encrypt TLS certificate. Use :80 for local HTTP testing.
APP_BASE_URL	https://agent.yourdomain.com	Public base URL where you access Scout (used for MCP OAuth callbacks and webhooks).

Security & Encryption Keys (Required)

Variable	How to Generate	Description
SESSION_SECRET	openssl rand -hex 32	Random 32-byte hex string used to sign authentication session cookies. Required—the server refuses to start if unset or left as the example placeholder.
ENCRYPTION_KEY	openssl rand -base64 32	32-byte base64 key (256-bit AES-GCM) used to encrypt OAuth tokens, channel tokens, and sensitive MCP headers at rest. Required—do not change after setup unless you intend to re-authenticate channels and MCP servers.
SESSION_COOKIE_SECURE	true	Set to true when serving over HTTPS (false only for local http://localhost development).
SIGNUP_ACTIVATION_CODE	Auto-generated on VM deploy	Optional one-time activation code required during initial owner registration.

Database Options

Variable	Example / Default	Description
DATABASE_URL	sqlite+aiosqlite:////app/data/scout.db	SQLAlchemy async connection URL. Supports sqlite+aiosqlite:// and postgresql+asyncpg:// (or postgresql://).
COMPOSE_PROFILES	(Unset for SQLite)	Set to local-db to run the bundled pgvector/pgvector:pg16 Postgres container, or cloudsql for the Google Cloud SQL Auth Proxy sidecar.
POSTGRES_USER	postgres	PostgreSQL username (when using local-db or cloudsql profile).
POSTGRES_PASSWORD	—	PostgreSQL password (when using local-db or cloudsql profile).
POSTGRES_DB	scout	PostgreSQL database name.
POSTGRES_HOST	cloudsql-proxy	Hostname for Cloud SQL Proxy mode.
CLOUDSQL_CONNECTION_NAME	project:region:instance	Google Cloud SQL instance connection name (when COMPOSE_PROFILES=cloudsql).
GOOGLE_APPLICATION_CREDENTIALS	/path/to/sa-key.json	Path to GCP service account key JSON for Cloud SQL Auth Proxy.

AI Provider Keys

Variable	Required?	Description
GOOGLE_API_KEY (or GEMINI_API_KEY)	Required	Google Gemini API key (pay-as-you-go recommended). Used for Gemini chat models, embeddings, compaction, and audio transcription.
ANTHROPIC_API_KEY	Optional	Anthropic API key (sk-ant-...) for Claude models.
OPENAI_API_KEY	Optional	OpenAI API key (sk-...) for GPT and o-series models.
OPENROUTER_API_KEY	Optional	OpenRouter API key (sk-or-...).
XAI_API_KEY	Optional	xAI API key (xai-...) for Grok models.
OLLAMA_HOST	Optional	Ollama base URL (e.g. http://host.docker.internal:11434).

Optional Channel Pre-Configuration

Channels can be configured interactively in the Web UI under Settings → Channels, or pre-populated via .env:

Variable	Description
TELEGRAM_BOT_TOKEN	Dedicated Telegram Bot token from @BotFather.
AGENTMAIL_API_KEY	API key from agentmail.to.