::quick install
One command. It installs Ollama if needed (or updates one older than 0.6.0), clones Saturn into ~/.saturday with its own virtualenv, pulls the small local chat model, and puts a saturn command on your PATH.
curl -fsSL saturdayai.org/install.sh | shThen open a new terminal and run saturn. The script is plain text at that URL, so you can download and read it before you run it. On macOS it installs Ollama with Homebrew; without Homebrew, install Ollama from ollama.com first. If ~/.local/bin isn't on your PATH, the installer offers to add it to your shell profile.
The installer defaults to the 4b tier (qwen3.5:4b). The first launch opens /models, which reads your hardware, prices every tier against it for fit and speed, lists any other models you've pulled, and asks which tier and embedder to run. Enter takes the recommendation, and anything not pulled yet is pulled once you agree. Re-run /models any time.
Right after the model pick, Saturn offers three quick questions: what to call you, what you do, and anything it should never do. Enter starts them, n skips, and any one can be skipped. Each answer is saved to memory in your words, so your first real request already knows who you are, and a "never…" answer becomes a rule loaded on every turn. The offer is made once. /memory setup asks them again later, with two more about the people you mention most and what you want help with. See memory.
| variable | default | what it does |
|---|---|---|
SATURN_TIER | 4b | the tier to activate: 4b, 9b, 27b, or 35b |
SATURN_INSTALL_DIR | ~/.saturday | where the clone and its virtualenv go |
SATURN_MODELS | qwen3.5:4b | the models the installer pulls |
SATURN_BRANCH | main | the branch to install from |
SATURN_BIN | ~/.local/bin | where the saturn launcher goes |
SATURN_REPO | the GitHub repo | the git URL to clone |
SATURN_MIN_OLLAMA | 0.6.0 | the oldest Ollama the installer accepts before it updates it |
The installer pulls the chat model only. The knowledge-base embedder (qwen3-embedding:8b) is pulled when you first run /docs add, and only if you agree. SATURN_TIER doesn't change what gets pulled: to install a larger tier up front, set SATURN_MODELS to its model too (SATURN_TIER=9b SATURN_MODELS=qwen3.5:9b), or let the first launch's /models offer the pull.
::pipx / uv
Saturn isn't on PyPI yet. pipx and uv install it straight from GitHub, as the saturn-agent package:
pipx install git+https://github.com/logansundaram/saturn
# or
uv tool install git+https://github.com/logansundaram/saturnYou still need Ollama running and the tier's chat model pulled. For the 4b tier that's ollama pull qwen3.5:4b. The first launch's /models page offers to run any missing pull (y/N, default no), and later launches warn about anything missing. Installed this way, your data and config.yaml live in ~/.saturn (override with SATURN_HOME). Update with pipx reinstall saturn-agent / uv tool install --reinstall git+https://github.com/logansundaram/saturn.
::from source
Prerequisites: Python 3.11+, git, and Ollama running locally.
git clone https://github.com/logansundaram/saturn
cd saturn
python -m venv .venv
source .venv/bin/activate
pip install -e .
ollama pull qwen3.5:4b
python agent.pyMore hardware to spare? Run /models and pick a larger tier, or set active_tier in config.yaml to 9b, 27b, or 35b and pull that tier's model. Small models are less reliable at choosing tools, so use the 9b or larger if your hardware fits it. saturn.sh launches from anywhere and prefers the repo's own .venv.
::requirements
os
macOS or Linux. The Notes, Calendar, Mail, Contacts, Reminders, Messages, Shortcuts, browser-tab, Finder, and notification tools need macOS. On Linux you get the file, shell, web, and knowledge-base tools.
runtime
Python 3.11+ and git, plus Ollama 0.6.0 or newer (the quick installer handles Ollama)
memory
the 4b tier fits on an 8 GB machine; 9b wants a 16 GB Mac, 27b a 32 GB Mac, 35b 36 GB or more of unified memory. /models checks this against your machine and also estimates speed: it recommends the largest tier that fits and runs at 10 tok/s or better, so a base-chip Mac may be steered to a smaller tier than its memory allows.
note
There's no API key step. Secrets for an MCP server's ${VAR} expansion are plain environment variables: export them in your shell, or put them in a .env file at the install (or ~/.saturn/.env for pipx/uv installs).
::updating
Clone and quick installs update with /update, or by re-running the install command, which updates the existing install in place. /update --check reports how many commits behind you are without changing anything, and /update reinstalls Python dependencies when pyproject.toml changed. pipx/uv installs reinstall from GitHub instead. Your data is never touched. The live config.yaml is user data that git doesn't track: it's seeded on first run from the template config.default.yaml, and settings you save land in it without dirtying the repo.