Self-Hosting with Docker Compose

The repository includes a production-ready docker-compose.yml stack featuring:

• Application Server (app): FastAPI backend, Vite-built frontend, and async background worker running in a single container.
• Caddy Reverse Proxy (caddy): Automatic HTTPS (Let’s Encrypt / ZeroSSL), HTTP/3 support, and unbuffered SSE streaming for live LLM tokens.
• Flexible Database Choices: Built-in persistent SQLite by default (zero setup), or connect to any PostgreSQL database (Supabase, Neon, AWS RDS, Cloud SQL, or bundled local Postgres).

---

1. Clone & Configure

git clone https://github.com/kcthota/scout.git
cd scout
cp .env.example .env

# Generate required secure secrets in .env:
sed -i.bak "s|replace_with_32_hex_session_secret|$(openssl rand -hex 32)|" .env
sed -i.bak "s|replace_with_base64_encryption_key|$(openssl rand -base64 32)|" .env && rm -f .env.bak

Add your GOOGLE_API_KEY (or GEMINI_API_KEY) in .env. Gemini is always required because embeddings, conversation compaction, and voice transcription use it.

Pay-As-You-Go Gemini Key

Use a pay-as-you-go key from Google AI Studio tied to a Google Cloud billing account. Using a free-tier key with an external harness like Scout may be against Google’s terms of service, and its rate limits cause failures during background tasks. Keys for other providers (OpenAI, Anthropic, OpenRouter, xAI, Ollama) are optional.

The application will refuse to start if SESSION_SECRET or ENCRYPTION_KEY are left as placeholders. Telegram and Email channels can be configured after startup in the web UI.

---

2. Choose Your Image & Deployment Method

Option A: Pre-Built Container Image from GHCR (Recommended)

No local build tools or language runtimes needed. Scout publishes official Docker images to GitHub Container Registry (ghcr.io/kcthota/scout).

1. If the GHCR package is private, authenticate Docker once with a GitHub Personal Access Token (read:packages scope):

   echo "<YOUR_GITHUB_TOKEN>" | docker login ghcr.io -u <YOUR_GITHUB_USERNAME> --password-stdin

2. Pull the latest image:

   docker compose pull

3. To pin a specific release version, set APP_IMAGE in your .env:

   APP_IMAGE=ghcr.io/kcthota/scout:v0.1.0

Option B: Build from Source Locally

To build the container image locally from the repository Dockerfile:

docker compose up -d --build

---

3. Choose Your Database in .env

Scout supports four database configurations out of the box:

Option A: Built-in SQLite (Default, Zero-Setup)

No extra configuration required. The SQLite database (scout.db) and uploaded media are stored in /app/data (persisted in the app_data Docker volume), and Goose conversation history and session continuity are persisted in the goose_data Docker volume:

DATABASE_URL=sqlite+aiosqlite:////app/data/scout.db

SQLite automatically uses the bundled sqlite-vec extension for fast indexed vector search across memories and knowledge documents.

Option B: External Cloud PostgreSQL

Set DATABASE_URL pointing to your hosted PostgreSQL instance (Supabase, Neon, AWS RDS, Cloud SQL Direct, etc.):

DATABASE_URL=postgresql://user:[email protected]:5432/scout?sslmode=require

Option C: Bundled Local PostgreSQL Container

To run a local PostgreSQL container (pgvector/pgvector:pg16) inside Docker Compose instead of SQLite, enable the local-db profile:

COMPOSE_PROFILES=local-db
DATABASE_URL=postgresql+asyncpg://postgres:replace_with_a_secure_password@postgres:5432/scout
POSTGRES_USER=postgres
POSTGRES_PASSWORD=replace_with_a_secure_password
POSTGRES_DB=scout

Faster Memory & Knowledge Search on PostgreSQL (pgvector)

Scout uses the pgvector extension when the PostgreSQL server has it. It runs CREATE EXTENSION IF NOT EXISTS vector automatically on first start (on managed services, enable pgvector in the provider’s console if your database user lacks superuser extension privileges). The bundled container in Option C ships with pgvector pre-installed. Without pgvector, semantic search still works by comparing embeddings in Python.

Option D: Google Cloud SQL Auth Proxy

To connect to Google Cloud SQL using IAM / Auth Proxy sidecar container, enable the cloudsql profile:

COMPOSE_PROFILES=cloudsql
CLOUDSQL_CONNECTION_NAME=your-gcp-project:region:instance-name
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
POSTGRES_HOST=cloudsql-proxy
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_cloudsql_password
POSTGRES_DB=scout

---

4. Launch Services

docker compose up -d

Access your agent at https://your-domain.com (or http://localhost when testing locally with DOMAIN=:80).

---

5. Upgrading

To upgrade to the latest container release:

docker compose pull app
docker compose up -d

Database schema migrations apply automatically on container startup (alembic upgrade head).

---

Container Registry & Versioning Reference

Scout Docker images are published to GitHub Container Registry at ghcr.io/kcthota/scout:

Tag	Description
latest	Latest stable release
vX.Y.Z (e.g. v0.1.0)	Specific immutable release tag
vX.Y (e.g. v0.1)	Latest patch release for minor version X.Y

Automated image publishing is handled by GitHub Actions (.github/workflows/publish-docker.yml) whenever a version tag (v*) is pushed to the repository.