Quickstart

Get Suitcase running in Docker, then configure from the setup dashboard.

Prerequisites

• Docker Desktop (running) with Docker Compose V2

That's it. No Node.js required — the Docker image builds its own web UI.

1. Install + guided setup

gh repo clone achuthanmukundan00/Suitcase   # or: git clone <url>
cd Suitcase
./scripts/setup.sh

setup.sh checks Docker, generates the Reactive Resume secrets, walks you through the optional keys (press Enter to skip any), and starts Suitcase + self-hosted Reactive Resume. It's safe to re-run anytime.

Flags: --full also starts the heavy runtime-full powers profile; --no-start configures without launching.

Once the repo is public, the whole thing is one line:

curl -fsSL https://raw.githubusercontent.com/achuthanmukundan00/Suitcase/main/scripts/install.sh | bash

2. Connect your model (default: browser login)

Open http://localhost:8000/setup and log in with Codex or Anthropic — an OAuth flow in the browser. No API key needed. Advanced users can instead set LLM_* in .env:

# Optional — only if you prefer an API key / custom endpoint over browser login
LLM_PROVIDER=openai                       # openai | openai-compatible | anthropic-compatible
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o
LLM_API_KEY=sk-your-key-here

# Recommended optional keys (setup.sh prompts for these)
GITHUB_TOKEN=                             # for repo evidence
BRAVE_API_KEY=                            # for web search

# ═══ OPTIONAL — Everything else is commented out ═══

OpenAI mode

When LLM_PROVIDER=openai, Suitcase auto-configures task-scoped models: gpt-4o for chat/trusted/vision and gpt-4o-mini for fast triage tasks. Switch to openai-compatible to use any provider with one model for everything.

2. Start (one command)

./start.sh

This handles:

1. Frontend build (npm install && npm run build) — one time
2. Docker compose up with health checks
3. Dependency checks (Docker, npm)
4. Prints the URLs and next steps

Flags

./start.sh --skip-build skips the frontend build.
./start.sh --stop stops everything.
./start.sh --logs tails container logs.

3. Setup dashboard

Open http://localhost:8000/setup.

Two numbered steps:

Step 1 — Connect your LLM. Pick OpenAI (default, with auto-configured task models), OpenAI-compatible, or Anthropic-compatible. Enter your API key and click Save and verify.

Step 2 — Enable your toolkit. Toggle powers ON/OFF. Powers with missing binaries auto-install via apt-get. Powers requiring tokens (Discord, Telegram, Brave, GitHub) have inline input fields.

Powers are organized into collapsible categories:

Category	Powers
Base	curl, jq, ripgrep, git, GitHub CLI, Brave Search
Documents	pandoc, poppler, tesseract, OCRmyPDF
Media	ffmpeg, sox, ImageMagick
Browser	Playwright
Cloud	rclone
Backups	restic
Secrets	pass
Messaging	Discord, Telegram
Location	GoPlaces, Geocode, Phone Location
Automation	Pulse, Command Logger, Session Memory
Runtime	Docker, Hamr

Once your LLM is connected, click Enter admin console to start chatting.

4. First chat (birth)

After entering the admin console:

1. Open Chat from the navigation
2. Suitcase introduces itself — this is the first-contact ritual
3. The agent has bash access to all enabled CLIs and reads SKILL.md files for guidance

5. Configuring secrets from the UI

Powers that require tokens (Discord, Telegram, Brave, GitHub, Restic) show inline password fields in the setup dashboard. Type the value and click Save — it's stored server-side and never returned to the browser.

For custom env vars not in the UI, use .env or the Admin console's danger zone.

Managing Suitcase

./start.sh --stop          # stop
./start.sh --logs          # tail logs
docker compose down -v     # stop + delete all data (destructive)

Self-Updating

Suitcase can check for and apply its own updates. The agent's self_update tool detects new versions from inside a conversation.

./scripts/update.sh           # git pull → rebuild → restart
./scripts/update.sh --check   # check for updates only
./scripts/update.sh --full    # include runtime-full profile

When the agent finds an update, it says "I'll be right back" — you run the command, and Suitcase restarts with the new version. Your data is safe in Docker volumes.

Next Steps

• Full Setup Guide — detailed walkthrough for each provider and power
• LLM Providers — OpenAI, Anthropic, LM Studio, Ollama
• Architecture — how Suitcase works under the hood
• Configuration — all environment variables and settings