Quickstart ​

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

Prerequisites ​

  • Docker with Docker Compose V2
  • Node.js 18+ — only needed for the first frontend build
  • An LLM endpoint — defaults to OpenAI; any OpenAI-compatible endpoint works

1. Install (one command) ​

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

This clones the repo, builds the frontend, creates .env, and starts Docker.

Flags: ./scripts/install.sh --full includes all powers. ./scripts/install.sh --dir ~/my-suitcase for a custom directory.

Or install manually ​

bash
git clone https://github.com/achuthanmukundan00/Suitcase.git
cd Suitcase
cp .env.example .env

Edit .env and set your LLM. The file is organized in three tiers:

bash
# ═══ REQUIRED — Chat won't work without these ═══
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              # ← set this

# ═══ RECOMMENDED — Better experience ═══
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) ​

bash
./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:

CategoryPowers
Basecurl, jq, ripgrep, git, GitHub CLI, Brave Search
Documentspandoc, poppler, tesseract, OCRmyPDF
Mediaffmpeg, sox, ImageMagick
BrowserPlaywright
Cloudrclone
Backupsrestic
Secretspass
MessagingDiscord, Telegram
LocationGoPlaces, Geocode, Phone Location
AutomationPulse, Command Logger, Session Memory
RuntimeDocker, Synax

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 ​

bash
./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.

bash
./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 ​

Your private career copilot.