Installation#

somnia has two halves and they have different appetites. The machine that renders books needs Kokoro, torch, ffmpeg and espeak-ng; the machine that serves them needs none of that. Most of the time they are the same box, and that is what the installer assumes.

You need Python 3.11, 3.12 or 3.13 — 3.14 is held back by pysbd, the sentence splitter, which is unmaintained. If the only python3 on the box is 3.14, the installer will use one of uv’s interpreters instead, or tell you how to get one.

Install#

curl -fsSLO https://raw.githubusercontent.com/gilesknap/somnia/main/scripts/somnia-install.sh
less somnia-install.sh
bash somnia-install.sh

Read it before you run it. It is a couple of hundred lines of shell and you are about to run it on a machine you care about; this page would tell you to do the same with anybody else’s installer.

It builds a virtual environment in ~/somnia-venv, installs somnia and the CPU build of torch, writes a starter ~/somnia.env with every setting commented out except the one that has no default, and pulls both book catalogs, Project Gutenberg and its Australian sibling. Run it twice and nothing is harmed: an existing environment is reused, and an existing settings file is never touched.

export PATH="$HOME/somnia-venv/bin:$PATH"   # or call ~/somnia-venv/bin/somnia in full

The installer prints this when it finishes, and nothing else does it for you: the environment is never activated, so until you do, somnia is not a command your shell knows. The other line it prints — source ~/somnia.env — is Configure, below.

It installs from main by default, not from the last release — this is the project’s own box-builder, and the box it builds is expected to be ahead. Pass --pypi for the released somnia-reader instead.

Flag	When
`--serve-only`	this machine only plays books: no Kokoro, no torch
`--venv DIR`	build it somewhere other than `~/somnia-venv`
`--ref REF`	install a branch, tag or commit rather than `main`
`--pypi`	install the last release from PyPI rather than a git ref
`--cuda`	you really do have a GPU
`--no-catalog`	skip the ~20MB catalog download

ffmpeg and espeak-ng cannot come from pip. They are the only things the installer will not fetch for you: it checks, and prints the command for your package manager if either is missing. Nothing else stops, because an environment without them is still worth having on a machine that only serves.

On Debian and Ubuntu there is a third, and it is not optional: python3-venv is a separate package, so a stock box has a Python that runs but cannot build a virtual environment. The installer checks for it and names it, but if you are installing by hand, get it first — matched to your interpreter:

sudo apt install ffmpeg espeak-ng python3.12-venv    # or python3.13-venv

Or by hand#

Four commands, and the order of the middle two matters:

python3 -m venv ~/somnia-venv
source ~/somnia-venv/bin/activate
python3 -m pip install torch --index-url https://download.pytorch.org/whl/cpu
python3 -m pip install "somnia-reader[ml]"

Install torch first, from the CPU index and nothing else. --extra-index-url is not enough: pip resolves across both indexes and takes the highest version it finds, so on the day PyPI carries a newer torch than the CPU index does you get two gigabytes of CUDA runtime to render a book with. Leave [ml] off on any machine that only serves.

The package is somnia-reader, not somnia. That name was taken on PyPI before this project existed, by an unrelated AI-agent CLI, so pip install somnia gets you a stranger’s package that will not answer to any command on this site. The extra name is the only thing that changed: import somnia and the somnia command are untouched.

Ahead of the last release#

A tagged release is a snapshot, and main moves. If you are chasing a fix that has landed but not been tagged — which the issue will normally say — install from the repository instead:

python3 -m pip install "somnia-reader[ml] @ git+https://github.com/gilesknap/somnia.git"

or plain bash somnia-install.sh, which is already what it does. Torch still goes in first, from the CPU index; nothing about that changes.

Into an environment that already has somnia in it, that command does nothing at all and says so cheerfully — see Upgrade to a new version for the uninstall that makes it stick.

Configure#

Everything is environment variables, and every one of them has a working default except the Anthropic key. ~/somnia.env is where the installer puts them and what the how-to guides assume — your shell reads it with source, and the systemd units read it with EnvironmentFile=.

Two of them matter on the first day. The rest have defaults that are right until you have a reason to change them, and are listed in Configuration.

Variable	Default	What it is
`ANTHROPIC_API_KEY`	—	The agent’s model calls. Required for `somnia ask` and `somnia serve`
`SOMNIA_LIBRARY_DIR`	`~/library/audiobooks`	Where rendered chapters are written, and served from

SOMNIA_LIBRARY_DIR is the one that fails quietly. Get it wrong and the server starts happily, answers questions happily, and 404s every chapter — the real reason is a warning in the journal, and what you see on the phone is only that chapter didn’t arrive. Set it explicitly.

There is nothing else to point somnia at. It renders the book, serves it and keeps your place, and it talks to no other server but Anthropic’s and Project Gutenberg’s.

Prove it works#

curl -fsSLO https://raw.githubusercontent.com/gilesknap/somnia/main/scripts/somnia-doctor.sh
bash somnia-doctor.sh

somnia doctor

  ok    somnia 0.1.dev45 in /home/you/somnia-venv
  ok    python 3.13.7
  ok    settings from /home/you/somnia.env
  ok    ffmpeg
  ok    espeak-ng
  ok    torch 2.13.0+cpu (CPU)
  ok    ANTHROPIC_API_KEY is set
  ok    catalog: 76421 books to search
  warn  no books added yet — try 'somnia add 271'
  warn  no library directory at /home/you/library/audiobooks — 'somnia add' will create it
  warn  nothing answering at http://127.0.0.1:8721 (only a problem if it should be running)

0 failed, 3 warned

It exits non-zero if anything failed, and it is worth running again after the first book: it checks that every rendered chapter is still on disk and still inside SOMNIA_LIBRARY_DIR, which is the failure you would otherwise meet at 2am as one chapter that didn’t arrive.

Add a book and ask it something is what to do next.

Or run it in a container#

Pre-built images with the dependencies already installed are on GitHub Container Registry — see Run in a container.