saturday.ai

::docs :: getting started

installation

The one-line installer, pipx/uv, and manual installs from source — plus the environment knobs each one honors.

::quick install

One command. It installs Ollama if needed, sets Saturn up in ~/.saturday in an isolated virtualenv, pulls the small local models, and puts a saturn command on your PATH.

macos / linux / wsl2
curl -fsSL saturdayai.org/install.sh | sh
windows (powershell)
irm saturdayai.org/install.ps1 | iex

Then open a new terminal and run saturn. The first run pulls a few GB of models, so it takes a minute. Both scripts are plain text at those URLs — download and read them first if you prefer.

variabledefaultwhat it does
SATURDAY_TIERlaptophardware tier to activate (laptop or workstation)
SATURDAY_HOME~/.saturdayinstall directory (your data lives here too)
SATURDAY_MODELSgemma4:e4b qwen3-embedding:8bmodels the installer pulls
SATURDAY_BRANCHmainbranch to install from

The installer defaults to the lightweight laptop tier. Switch to a bigger tier any time from inside Saturn with /models tier workstation.

::pipx / uv

Saturn ships on PyPI as saturn-agent:

pipx install saturn-agent
# or
uv tool install saturn-agent

You still need Ollama running and the tier models pulled — for the laptop tier that's ollama pull gemma4:e4b and ollama pull qwen3-embedding:8b. /config setup reports what's missing and offers to run the pulls for you (default no). Installed this way your data and config.yaml live in ~/.saturday; upgrade with pipx upgrade saturn-agent / uv tool upgrade saturn-agent.

::from source

Prerequisites: Python 3.11+, git, and Ollama running locally.

git clone https://github.com/logansundaram/saturn
cd saturn
python -m venv .venv
# Windows: .venv\Scripts\activate   macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
ollama pull qwen3.6:27b          # the workstation tier's model
ollama pull qwen3-embedding:8b   # the embedder (RAG)
python agent.py

Lighter on hardware? Set active_tier: laptop in config.yaml and pull gemma4:e4b instead (same embedder). Small models are less reliable at tool-calling; /config setup will say so. saturn.cmd (Windows) and saturn.sh (macOS/Linux) launch from anywhere and prefer the repo's own .venv.

::requirements

os

macOS 13+, Linux, WSL2, or Windows 10/11

runtime

Python 3.11+ and git (the quick installer handles both)

memory

8 GB RAM minimum for the laptop tier; 16 GB+ recommended

disk

~6 GB free for the local models

note

There is no API key step. Secrets for MCP servers' ${VAR} expansion are plain environment variables — put them in a .env file next to the install (or ~/.saturday/.env for pipx installs).

::updating

Clone and quick installs update with /update (/update --check reports how many commits behind you are without changing anything); pipx/uv installs use their own upgrade command. Your data under database/ is never touched. The live config.yaml is user data and is not tracked by git — it is seeded on first run from the template config.default.yaml, and persisted settings land in it without dirtying the repo.