System Requirements
Suitcase runs locally. The backend, frontend, database, world files, and optional Discord bot all live on your machine.
Required
| Requirement | Version / Notes |
|---|---|
| Python | 3.10 or newer |
| Node.js | 18 or newer, used to build the React frontend |
| npm | Bundled with Node.js |
| SQLite | Used through Python's standard library |
| Git | Needed to clone the repository |
| LLM endpoint | Relay with llama.cpp is the recommended free local option |
Recommended Local LLM Setup
For local inference, use Relay with llama.cpp. It exposes an OpenAI-compatible local server for GGUF models.
Verified local baseline:
| Model | Runtime |
|---|---|
| Gemma 4 26B MoE (A4B active) IQ4_XS quantized | Relay with llama.cpp |
Smaller local models can run, but Suitcase has a substantial system prompt and world context. Models below 8B parameters may struggle with instruction following, safety boundaries, and consistent personality.
Hardware Guidance
| Use case | Suggested machine |
|---|---|
| Cloud LLMs only | Any modern laptop or desktop that can run Python and Node.js |
| Local 8B models | 16 GB RAM minimum |
| Local 20B+ quantized models | 32 GB RAM or unified memory recommended |
| Smooth local daily use | Apple Silicon with enough unified memory, or a GPU-backed Linux/Windows machine |
Exact memory needs depend on model size, quantization, context length, and runtime settings.
Ports
| Service | Default port |
|---|---|
| Suitcase FastAPI app | 8000 |
| Vite frontend dev server | 5173 |
Relay with llama.cpp | commonly 8080 |
| LM Studio | 1234 |
| Ollama | 11434 |
Optional Integrations
| Integration | Requirement |
|---|---|
| Discord bot | Discord application, bot token, and target user or channel ID |
| GitHub sync | GitHub username; token recommended for private repos and higher rate limits |
| Cloudflare Access | Client ID and client secret headers configured in setup |
Filesystem
Suitcase writes application data under the repository:
app/data/applications.dbfor SQLite statesuitcase_world/for world files, reflections, artifacts, patch proposals, and agent-visible memory.envfor server-side secrets and configuration
See Sandboxing & Security for how write boundaries are enforced.