Configuration

Reference for all Suitcase configuration behavior.

Where Config Comes From

Suitcase resolves config from these layers (highest priority first):

1. Environment (.env / container env vars)
2. Server-side saved setup values (LLM settings + secrets, persisted by the Setup UI)
3. OpenAI defaults (when LLM_PROVIDER=openai, auto-configures gpt-4o, gpt-4o-mini, etc.)
4. Hardcoded defaults

.env Tiers

REQUIRED

Variable	Description
LLM_PROVIDER	openai, openai-compatible, or anthropic-compatible
LLM_BASE_URL	Endpoint URL (e.g. https://api.openai.com/v1)
LLM_MODEL	Model name (e.g. gpt-4o)
LLM_API_KEY	API key — the only must-set value

RECOMMENDED

Variable	Description
GITHUB_TOKEN	For repo evidence sync
BRAVE_API_KEY	For web search via Brave Search API

OPTIONAL

Everything else is commented out by default:

• LLM tuning (LLM_TEMPERATURE, LLM_MAX_TOKENS, LLM_TIMEOUT_SECONDS)
• Task-scoped model overrides (LLM_CHAT_MODEL, LLM_FAST_MODEL, LLM_TRUSTED_MODEL, LLM_VISION_MODEL)
• Vision model (LLM_VISION_ENABLED, etc.)
• Discord / Telegram integration
• Job board API keys
• Feature flags
• Pulse interval
• Phone location webhook secret
• Restic backup credentials

Provider Modes

OpenAI (default)

LLM_PROVIDER=openai

Auto-configures:

• https://api.openai.com/v1 as base URL
• gpt-4o for chat, trusted, and vision tasks
• gpt-4o-mini for fast triage tasks

Task-scoped models can be overridden via env vars or the Setup UI.

OpenAI-compatible

LLM_PROVIDER=openai-compatible
LLM_BASE_URL=https://your-endpoint/v1
LLM_MODEL=your-model

One model for all tasks. Works with LM Studio, Ollama, OpenRouter, DeepSeek, Groq, etc.

Anthropic-compatible

LLM_PROVIDER=anthropic-compatible
LLM_BASE_URL=https://api.anthropic.com
LLM_MODEL=claude-sonnet-4-20250514

One model for all tasks.

Startup

cp .env.example .env   # edit LLM_API_KEY at minimum
./start.sh             # builds frontend + starts Docker

./start.sh handles:

• Dependency checks (Docker, npm)
• Frontend build (one-time)
• .env creation from .env.example if missing
• Docker compose up with health checks

See ./start.sh --help for all options.

Runtime Data Locations

Volume	Container Path	Contents
suitcase-data	/data	SQLite DB, user profile, secrets
suitcase-world	/suitcase_world	World files, reports, artifacts, memory, command logs
suitcase-logs	/logs	Web and pulse logs

Installed CLIs

The web image includes: curl, jq, git, gh, rg, pandoc, pdftotext, tesseract, ocrmypdf, ffmpeg, sox, convert, rclone, restic, pass, docker.

Playwright and Chromium are installed in the runtime profile image.

Port

Default: 8000. Override with SUITCASE_PORT in .env.

Pulse

The suitcase-pulse container wakes every SUITCASE_PULSE_INTERVAL seconds. Set to 0 to disable. Configurable from the Setup UI with a dropdown (Disabled, 5m, 15m, 30m, 1h, 4h, 24h).

Write Confinement

All writes must resolve inside suitcase_world/. Symlink escapes and parent-directory traversal are blocked.

Reset

Admin Console → Reset database clears career data and re-runs setup gating. Environment-level config (.env, LLM settings) is preserved.

Secrets from the UI

Powers that require tokens show inline password fields in the Setup dashboard. Values are stored via POST /api/setup/secrets and never returned to the browser. Supported keys: DISCORD_BOT_TOKEN, GITHUB_TOKEN, BRAVE_API_KEY, TELEGRAM_BOT_TOKEN, RESTIC_PASSWORD, RESTIC_REPOSITORY, STRIPE_API_KEY, PHONE_LOCATION_WEBHOOK_SECRET, SUITCASE_PULSE_INTERVAL, and task-scoped model overrides.