Installation
Pick the install path that matches how you want to run Soriku: native Python on your machine, Docker, or a managed cloud later.
System requirements
| Component | Minimum | Recommended |
|---|---|---|
| CPU | Apple Silicon or x86_64 | Apple Silicon M-series or AMD/Intel with AVX2 |
| RAM | 8 GB | 16 GB unified memory or more |
| Disk | 1 GB for the app | 4–40 GB for models, depending on which you pull |
| GPU | Optional | Metal / CUDA / ROCm for faster local inference |
| Network | Not required for local mode | Only needed for remote providers and updates |
| OS | macOS 12+, Linux, Windows 11 | macOS 14+ (best tested) or Ubuntu 22.04+ |
Native Python install
The most flexible path. You control the Python version, the virtualenv and which dependencies you pull in.
git clone https://github.com/atypisch/soriku.git
cd soriku
python -m venv .venv && source .venv/bin/activate
pip install -e ".[all]"
# verify
python -c "import core; print(core.__version__)"
python server.py
Install extras
The pyproject.toml defines a handful of optional groups so you can keep the install small.
| Extra | Pulls in | When to use |
|---|---|---|
[server] | FastAPI, Uvicorn, SSE streaming | Bare minimum to run the HTTP server |
[mcp] | MCP SDK and stdio transport | When you want to expose Soriku to Cursor or VS Code |
[documents] | PDF, DOCX, EPUB parsing | When you want agents to read documents in pilot mode |
[billing] | Stripe SDK and webhook handlers | Only for hosted Soriku Cloud with paid plans |
[voice] | Whisper (CPU) and audio decoders | For the /api/v1/voice endpoint |
[all] | Everything above | Default for development and most users |
Docker
Ships with a docker-compose.yml that brings up Soriku and Ollama together in two containers.
docker compose up -d
# pull a model inside the ollama container
docker compose exec ollama ollama pull qwen2.5-coder:7b
# logs
docker compose logs -f soriku
On macOS Docker runs in a Linux VM, so Metal GPU acceleration is not available inside the container. For local development on Apple Silicon the native Python install is much faster.
Verify the install
# server should be live
curl -s http://localhost:8765/api/health | jq
# OpenAI-compatible endpoint should respond
curl -s http://localhost:8765/api/v1/models | jq
Updating
cd soriku
git pull
pip install -e ".[all]" --upgrade
Database migrations run automatically on the next server start. Your agent personas, capability map and routing logs all stay where they were.