Full Setup Guide
Suitcase setup is a single dashboard page. Connect your LLM, toggle the powers you want, and start chatting.
One-Command Install
curl -fsSL https://raw.githubusercontent.com/achuthanmukundan00/Suitcase/main/scripts/install.sh | bashThis clones, builds, configures, and starts Suitcase. Edit .env to set LLM_API_KEY, then open the setup dashboard.
Or manually:
git clone https://github.com/achuthanmukundan00/Suitcase.git
cd Suitcase
cp .env.example .env # set LLM_API_KEY
./start.sh # builds frontend, starts DockerOpen http://localhost:8000/setup.
Step 1 — Connect your LLM
The LLM is Suitcase's brain. Pick one of three modes:
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 |
Base URL defaults to https://api.openai.com/v1. Just enter your API key and click Save and verify.
OpenAI-compatible
One model for all tasks. Use this for LM Studio, Ollama, OpenRouter, DeepSeek, Groq, or any custom endpoint. You provide the base URL and model name.
Anthropic-compatible
One model for all tasks. Use this for Anthropic's API directly or through a proxy.
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 | — |
| Synax | Runtime | bun | — |
Pulse Configuration
Below the LLM 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.