System Requirements
Suitcase runs entirely in Docker containers. No Python, no Node.js, no SQLite needed on your host (except Node.js to build the frontend once — which ./start.sh handles for you).
Required
| Requirement | Notes |
|---|---|
| Docker | With Docker Compose V2 plugin |
| Node.js 18+ | Only for building the React frontend (one-time) |
| Git | To clone the repository |
| LLM endpoint | Local or cloud — see LLM Providers |
Docker Containers
| Service | Image | Purpose |
|---|---|---|
suitcase-web | suitcase-web:latest | FastAPI + React SPA (port 8000) |
suitcase-pulse | suitcase-web:latest | Autonomous wake-up worker |
suitcase-runtime | suitcase-runtime:latest | Agent tool sandbox (profile) |
All durable state lives in named Docker volumes (suitcase-data, suitcase-world, suitcase-logs). Nothing writes into your source tree.
Hardware Guidance
| Use case | Suggested machine |
|---|---|
| Cloud LLMs only | Any modern machine that runs Docker |
| Local 8B models | 16 GB RAM minimum |
| Local 20B+ quantized models | 32 GB RAM or unified memory |
| Smooth local daily use | Apple Silicon with enough unified memory, or GPU-backed Linux |
Ports
| Service | Default port |
|---|---|
| Suitcase web UI | 8000 |
| LM Studio | 1234 |
| Ollama | 11434 |
| llama.cpp / Relay | 8080 |
Optional Integrations
| Integration | Requirement |
|---|---|
| Discord bot | Discord application, bot token, target user/channel ID |
| GitHub sync | GitHub username; token recommended for private repos |
| Telegram bot | Bot token from BotFather, allowed user IDs |
| Cloudflare Access | Client ID and client secret headers |
Disk Space
| Component | Approximate size |
|---|---|
Web image (suitcase-web) | ~570 MB |
Runtime image (suitcase-runtime) | ~3.3 GB (includes Playwright + Chromium) |
| Docker volumes | Grows with usage (DB, world files, logs) |
The runtime image is only needed when using --profile runtime for browser automation. The web image alone is sufficient for normal use.