AI Connections

AI is optional in Nostos. The Library, the readers, the Brain and the Writing Studio all work without it. If you want the AI features, you connect them to AI services yourself in Settings → AI connections.

Nostos Cloud sets all of this up for you. This page is only for self-Nostos Cloud.

What each connection does

The page has five connections. Each one is separate, so you can set up only the ones you want.

Connection	What it does	Route Nostos calls
Reading assistant	Ask Nostos: answers questions about your library, captures thoughts and suggests topics	POST …/chat/completions
Voice transcription	Turns voice recordings into text	POST …/v1/audio/transcriptions
Alignment transcription	Lets you jump from a place in an audiobook to the same sentence in the ebook of the same book	POST …/v1/audio/transcriptions
Embeddings	Builds a search index of your books’ text so Ask Nostos can find passages by meaning, not only by matching words	POST …/embeddings
Read aloud voice	A natural-sounding voice for reading EPUBs and PDFs aloud	POST …/v1/audio/speech

All five use the OpenAI API format. Nostos does not need OpenAI itself: any service that offers the same routes works. That includes OpenAI, gateways such as OpenRouter, and servers on your own machine such as Ollama, LM Studio, vLLM, Speaches or Kokoro.

What leaves your server

Your server sends notes, questions, voice recordings and passages from your books to the endpoints you set here. Your browser does not talk to them. If nothing may leave your network, use services that run on your own machine.

Set up a connection

Every connection has the same fields:

1. Endpoint: the service’s base URL, including /v1, for example https://api.openai.com/v1. A server in the same Docker Compose project is reached by its service name, for example http://ollama:11434/v1.
2. Model: the exact model name the service expects. Press Load models to choose from the list the service provides, if it provides one.
3. API key: leave it empty for a service on your own network that has no login. Nostos stores the key on your server and never sends it back to the browser.
4. Press Test connection. Nostos makes one real request and reports what came back.
5. Press Save at the bottom of the page.

Voice transcription, alignment, embeddings and read aloud each also have an Enable switch. A connection with its switch off does nothing, even if the rest is filled in.

Voice transcription on an older Nostos

Older Nostos releases add /v1 to the voice and alignment transcription endpoints themselves. If Test connection reports a “not found” error for those two, remove /v1 from the end of the endpoint.

Reading assistant

This is the model behind Ask Nostos. The model must support tool calling. Ask Nostos searches your library, saves captures and proposes topics by calling tools. A model that ignores tools will say it did something it did not do.

After you save the connection, turn the assistant on in Settings → Assistant → Show reading assistant. The assistant then appears in the dock.

Voice transcription

This turns voice recordings into text. Use any model that offers the OpenAI transcription route, such as whisper-1 on OpenAI or a Whisper model on a Speaches server.

Alignment transcription

When you own an audiobook and the ebook of the same book, alignment lets you jump between them and land on the same sentence. Nostos transcribes a few short clips of the audiobook and finds that text in the ebook.

Turn on Use my voice transcription setup to use the voice transcription connection for this too. That is the simplest choice. To use a different service, turn it off and enter that service’s details. The API style for almost every service is OpenAI-compatible (multipart upload).

Embeddings

When this is on, Nostos indexes your books’ text in the background and builds the index again if you change the model. Ask Nostos uses the index to find passages that mean the same thing in different words. When this is off, or the service can’t be reached, Ask Nostos still works but finds passages by matching words only.

Read aloud voice

Every device can already read books aloud with its own voice. This connection gives every device the same natural-sounding voice from a speech server, such as Kokoro running next to Nostos. Read Aloud explains the setup step by step.

Example setups

OpenAI for everything

Connection	Endpoint	Model
Reading assistant	https://api.openai.com/v1	a current chat model, e.g. gpt-4o-mini
Voice transcription	https://api.openai.com/v1	whisper-1
Embeddings	https://api.openai.com/v1	text-embedding-3-small

Use the same API key for each.

Everything on your own machine

Add the servers to the Compose file that runs Nostos. Nostos reaches each one by its service name:

services:
  nostos:
    image: ghcr.io/christian-gennari/nostos:latest
    # ...your existing nostos service, unchanged

  ollama:
    image: ollama/ollama
    volumes:
      - ollama:/root/.ollama
    restart: unless-stopped

  kokoro:
    # Pin a release tag from the Kokoro-FastAPI project instead of `latest`.
    image: ghcr.io/remsky/kokoro-fastapi-cpu:latest
    restart: unless-stopped

volumes:
  ollama:

Download the models into Ollama with docker compose exec ollama ollama pull <model>. Then connect:

Connection	Endpoint	Model
Reading assistant	http://ollama:11434/v1	a model that supports tool calling
Embeddings	http://ollama:11434/v1	an embedding model, e.g. nomic-embed-text
Read aloud voice	http://kokoro:8880	kokoro

Ollama can’t transcribe audio. For voice and alignment transcription, run a server that offers the OpenAI transcription route, such as Speaches, and connect it the same way.

A small model running on a CPU is slow, and the smaller the model, the less reliably it calls tools. If Ask Nostos makes mistakes, try a larger model or a hosted one first.

Set connections in configuration instead

You can also set the connections with environment variables or in appsettings.json. This is useful when a script sets up your server. Anything saved in Settings takes precedence over configuration.

Connection	Configuration section	Key from environment variable
Reading assistant	Assistant	NOSTOS_ASSISTANT_TOKEN
Voice transcription	Speech	NOSTOS_STT_TOKEN
Embeddings	Embedding	NOSTOS_EMBEDDING_TOKEN
Read aloud voice	ReadAloud	NOSTOS_READ_ALOUD_TOKEN

Each section takes Enabled, BaseUrl and Model. In Compose, separate the section and the setting with two underscores:

services:
  nostos:
    environment:
      Assistant__BaseUrl: https://api.openai.com/v1
      Assistant__Model: gpt-4o-mini
      NOSTOS_ASSISTANT_TOKEN: ${OPENAI_API_KEY}

To use the configuration again after you saved a key in Settings, press Clear key in Settings.

When something doesn’t work

• Test connection fails with 401 or 403. The API key is missing or wrong, or it doesn’t have access to that model.
• Test connection fails with 404. The endpoint is wrong. Check that it ends in /v1, and see the note above about voice transcription on older releases.
• Load models returns nothing. Some services don’t list their models. Type the model name instead.
• Ask Nostos says it saved something, but nothing is there. The model is not calling tools. Choose a model that supports tool calling.
• Nostos can’t reach a service on the host machine. Inside the container, localhost is the container itself. Use the service’s Compose name, or the host’s network address.