Full Setup Guide
Suitcase setup is a single dashboard page. Connect a model through Hamr, toggle the powers you want, and start chatting.
Install + guided setup
Only prerequisite: Docker Desktop, running. No Node.js — the image builds its own web UI.
gh repo clone achuthanmukundan00/Suitcase # or: git clone <url>
cd Suitcase
./scripts/setup.shsetup.sh is guided and re-runnable: it checks Docker, auto-generates the Reactive Resume secrets, prompts you through the optional keys (Enter skips any), and starts Suitcase + self-hosted Reactive Resume. Then open http://localhost:8000/setup.
Once the repo is public, one line does everything:
curl -fsSL https://raw.githubusercontent.com/achuthanmukundan00/Suitcase/main/scripts/install.sh | bashStep 1 — Connect your model
The model is Suitcase's brain. The setup UI mirrors Hamr:
- Login with OpenAI OAuth or Login with Claude OAuth when available.
- Use a provider API key by selecting provider + key + model. No endpoint needed.
- Custom OpenAI/Anthropic-compatible endpoint for LM Studio, Ollama-compatible proxies, private relays, or gateways.
OpenAI (default)
Suitcase auto-configures task-scoped models:
| Task | Model |
|---|---|
| Chat | gpt-4o |
| Fast (triage, extraction) | gpt-4o-mini |
| Trusted (applications, reviews) | gpt-4o |
| Vision (PDF review) | gpt-4o |
In provider API-key mode, select OpenAI, paste your key, choose a model, and save. No base URL is required.
OpenAI-compatible
Use the custom endpoint form for LM Studio, Ollama-compatible proxies, private relays, gateways, or any endpoint that is not handled by Hamr's provider catalog. You provide the base URL and model name. Local endpoints can leave the API key blank.
Anthropic-compatible
Use this for Anthropic's API directly or through a proxy.
Hamr provider auth
Provider API keys are saved in Hamr auth and then used by Suitcase's Hamr bridge. Custom endpoint keys are saved in Suitcase's local secret store.
Step 2 — Enable your toolkit
27 powers organized into collapsible categories. Each power card shows:
- ON/OFF toggle — clicking ON on a power with missing binaries auto-runs
apt-get install - Binary status — green ✓ or red ✗ for each required CLI
- Env var status — green ✓ or red ✗ for each required token
- Why? button — shows exact missing pieces and install guidance (only when not ready)
- Inline input fields — for token-requiring powers (Discord, Telegram, Brave, GitHub, Restic)
Power Reference
| Power | Category | Binaries | Env Vars |
|---|---|---|---|
| curl | Base | curl | — |
| jq | Base | jq | — |
| Ripgrep | Base | rg | — |
| Git | Base | git | — |
| GitHub CLI | Base | gh | GITHUB_TOKEN |
| Brave Search | Base | curl | BRAVE_API_KEY |
| Pandoc | Documents | pandoc | — |
| Poppler | Documents | pdftotext | — |
| Tesseract OCR | Documents | tesseract | — |
| OCRmyPDF | Documents | ocrmypdf | — |
| FFmpeg | Media | ffmpeg | — |
| SoX | Media | sox | — |
| ImageMagick | Media | convert | — |
| Playwright | Browser | — | — |
| Rclone | Cloud | rclone | — |
| Restic | Backups | restic | RESTIC_REPOSITORY, RESTIC_PASSWORD |
| Pass | Secrets | pass | — |
| Discord | Messaging | — | DISCORD_BOT_TOKEN |
| Telegram | Messaging | — | TELEGRAM_BOT_TOKEN |
| GoPlaces | Location | goplaces | — |
| Geocode | Location | geocode | — |
| Phone Location | Location | — | PHONE_LOCATION_WEBHOOK_SECRET |
| Pulse | Automation | — | SUITCASE_PULSE_INTERVAL |
| Command Logger | Automation | — | — |
| Session Memory | Automation | — | — |
| Docker | Runtime | docker | — |
| Hamr | Runtime | bun | — |
Pulse Configuration
Below the model connection card, a Pulse Interval card lets you configure the autonomous wake-up worker:
| Option | Interval |
|---|---|
| Disabled | 0 |
| 5 minutes | 300 |
| 15 minutes | 900 |
| 30 minutes | 1800 |
| 1 hour | 3600 |
| 4 hours | 14400 |
| 24 hours | 86400 |
The pulse worker checks for new leads, runs reflections, and proposes patches. It never messages you by default.
Command Logger
Enable the Command Logger power to write every tool call to suitcase_world/logs/commands.log (JSONL format, secrets redacted). Useful for auditing and debugging.
Session Memory
Enable the Session Memory power to persist each chat exchange to suitcase_world/memory/sessions/ as timestamped markdown files.
Brave Search
Set BRAVE_API_KEY via the inline input field or .env. The agent can then use the Brave Search API for web search:
curl -s "https://api.search.brave.com/res/v1/web/search?q=QUERY" \
-H "X-Subscription-Token: $BRAVE_API_KEY" | gunzip | jqSKILL.md guidance enforces a 1-second rate limit between requests.
Phone Location
Set PHONE_LOCATION_WEBHOOK_SECRET to enable phone location webhooks. Use with OwnTracks, GPSLogger, or Tasker to send location updates to Suitcase.
After Setup
- Click Enter admin console
- Open Chat — Suitcase introduces itself (first-contact ritual)
- The agent has bash access to all enabled CLIs and reads SKILL.md files for guidance
Security Audit
Before trusting a new setup, run the security audit:
./scripts/security_audit.sh # baseline check
./scripts/security_audit.sh --deep # deep scan for secrets
./scripts/security_audit.sh --fix # auto-fix permissionsThe audit checks network binding, channel DM policies, secret storage, file permissions, and Docker safety. Fix any critical or high findings before exposing Suitcase beyond localhost.
See Sandboxing & Security for the full security guidance.