Configuration Reference

SeeSee is configured entirely through environment variables. All variables use the SEESEE_ prefix.

Copy .env.example from the repository as a starting template.

Server

Variable	Type	Default	Description
SEESEE_PORT	int	8080	HTTP server port
SEESEE_BASE_URL	string	http://localhost:8080	Public base URL of the service. Set this to your https:// URL on a real deployment — it builds the integration ENV vars, and it is the fallback that marks cookies Secure if the proxy’s forwarded scheme is not trusted
SEESEE_FORWARDED_ALLOW_IPS	string	(private ranges — see below)	Which client IPs may set X-Forwarded-Proto / X-Forwarded-For

SEESEE_FORWARDED_ALLOW_IPS

SeeSee runs behind a reverse proxy that terminates TLS, and it has to trust that proxy’s X-Forwarded-Proto — otherwise it can’t tell an HTTPS request from an HTTP one, and session and flash cookies lose their Secure flag. uvicorn’s own default (127.0.0.1) never matches a proxy running in a separate container, which is every containerized deployment: Coolify, Docker Compose, and Kubernetes all connect from a private network address.

The default therefore trusts the private ranges a containerized proxy actually connects from, and nothing else:

127.0.0.0/8,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,100.64.0.0/10,fc00::/7

Accepts a comma-separated list of IP addresses and CIDR networks, or * to trust every client.

Caution

Prefer narrowing this over widening it. * trusts any client that can open a connection to SeeSee’s HTTP port, which on a directly-exposed instance means an attacker can forge X-Forwarded-For and control what the access log records as the source of every request. If you know your proxy’s address, set it explicitly — SEESEE_FORWARDED_ALLOW_IPS=10.0.1.5 is tighter than the default.

Set this explicitly if your proxy reaches SeeSee over a public address (a proxy on a different host, with no private network between them). Nothing in the default list will match it, the forwarded scheme will be dropped, and cookies will only stay Secure because SEESEE_BASE_URL is an https:// URL — so make sure it is. SeeSee logs a startup warning when it isn’t.

Requires uvicorn ≥ 0.31 for CIDR support; the pinned dependency already covers this.

Authentication

Variable	Type	Default	Description
SEESEE_ADMIN_USERNAME	string	admin	Admin username for Web UI and API basic auth
SEESEE_ADMIN_PASSWORD	string	(required)	Admin password — must be set, no default

Caution

SEESEE_ADMIN_PASSWORD has no default value. SeeSee will not start without it. Choose a strong password for production deployments.

Database

Variable	Type	Default	Description
SEESEE_DB_PATH	string	/data/seesee.db	Path to the SQLite database file

The database directory must be writable. In Docker, mount a volume at /data for persistence.

SMTP Ingest

Variable	Type	Default	Description
SEESEE_SMTP_ENABLED	bool	true	Enable the built-in SMTP server
SEESEE_SMTP_PORT	int	2525	SMTP server listen port

Retention

Retention rules control automatic cleanup. The most restrictive rule wins.

Variable	Type	Default	Description
SEESEE_RETENTION_MAX_COUNT	int	1000	Maximum emails to keep per app. Oldest are deleted first
SEESEE_RETENTION_MAX_AGE_DAYS	int	90	Delete emails older than this many days
SEESEE_RETENTION_MAX_STORAGE_MB	int	500	Global storage cap in MB. Oldest emails deleted first when exceeded
SEESEE_RETENTION_CLEANUP_INTERVAL_MINUTES	int	60	How often the retention scheduler runs (in minutes)
SEESEE_RETENTION_DEGRADE_TO_TEXT_DAYS	int	0	Strip HTML body after N days, keeping text + preview. 0 = never degrade
SEESEE_RETENTION_DEGRADE_TO_PREVIEW_DAYS	int	0	Strip text body after N days, keeping preview only. 0 = never degrade

Apps can override max_count, max_age_days, degrade_to_text_days, and degrade_to_preview_days with per-app values set during app creation or update. For retention limits, the effective value is the minimum of the per-app and global value. For degradation thresholds, a per-app override can enable degradation even if the global setting is disabled.

Session

Variable	Type	Default	Description
SEESEE_SECRET_KEY	string	(falls back to admin password)	Secret key for signing session cookies. Set a unique value in production
SEESEE_SESSION_MAX_AGE_DAYS	int	7	Session cookie expiry in days

Tip

Set SEESEE_SECRET_KEY to a unique random string in production. If not set, it falls back to SEESEE_ADMIN_PASSWORD, which means changing your password will invalidate all sessions.

UI

Variable	Type	Default	Description
SEESEE_THEME	string	system	Default theme: light, dark, or system (follows OS preference)
SEESEE_DISPLAY_TIMEZONE	string	UTC	IANA timezone string for admin date display (e.g. America/Chicago, Europe/London). Controls how dates appear in admin views only — does not affect storage (always UTC) or API responses (always UTC ISO 8601)

Webhook Secrets

Optional secrets for verifying webhook payloads from email providers. If not set, signature verification is skipped (a warning is logged).

Variable	Type	Default	Description
SEESEE_WEBHOOK_SECRET_RESEND	string	(empty)	Svix signing secret from the Resend dashboard (starts with whsec_)
SEESEE_WEBHOOK_SECRET_SENDGRID	string	(empty)	Shared secret for SendGrid webhook token verification

Tip

For production deployments, always configure webhook secrets to prevent unauthorized status updates. See the Webhooks API reference for setup instructions.

Logging

Variable	Type	Default	Description
SEESEE_LOG_LEVEL	string	info	Log level: debug, info, warning, error, critical

Screenshot coming soon

Brandon, put a screenshot here showing the theme selector grid on the settings page — all 21 themes look great and people should see them. If you’re reading this, feel free to remind him — and send a screenshot along if you have one!

Example .env file

# Required
SEESEE_ADMIN_PASSWORD=change-me-to-something-secure

# Server
SEESEE_PORT=8080
SEESEE_BASE_URL=https://seesee.example.com

# Database (default is fine for Docker)
SEESEE_DB_PATH=/data/seesee.db

# SMTP
SEESEE_SMTP_ENABLED=true
SEESEE_SMTP_PORT=2525

# Retention
SEESEE_RETENTION_MAX_COUNT=1000
SEESEE_RETENTION_MAX_AGE_DAYS=90
SEESEE_RETENTION_MAX_STORAGE_MB=500
SEESEE_RETENTION_DEGRADE_TO_TEXT_DAYS=0
SEESEE_RETENTION_DEGRADE_TO_PREVIEW_DAYS=0

# UI
SEESEE_DISPLAY_TIMEZONE=UTC  # e.g. "America/Chicago", "Europe/London"

# Session
SEESEE_SECRET_KEY=your-random-secret-key
SEESEE_SESSION_MAX_AGE_DAYS=7

# Webhook secrets (optional)
SEESEE_WEBHOOK_SECRET_RESEND=whsec_your_resend_signing_secret
SEESEE_WEBHOOK_SECRET_SENDGRID=your-sendgrid-shared-secret

# Logging
SEESEE_LOG_LEVEL=info