Deploy and Host Odysseus on Railway

Odysseus is a self-hosted AI workspace. It puts chat and agents, multi-step web research, a writing-first document editor, an email inbox, notes, tasks and a calendar behind a single login on an instance you own. This template deploys it along with the two supporting services it expects, a vector store and a private search engine, so retrieval and web search work on the first boot rather than failing quietly.

About Hosting Odysseus

Odysseus is built to run as a small cluster rather than a single container. The app itself is a Python service, but its default search provider is a separate SearXNG instance and its retrieval layer talks to a standalone Chroma server over HTTP. The Python package it installs for that is the thin HTTP client only, so there is no embedded fallback: deploy the app on its own and semantic memory, retrieval and the tool picker all degrade to keyword matching, while every web search and every Deep Research run comes back empty.

Two details make self-hosting it fiddlier than it looks. SearXNG serves HTML only unless its JSON output is explicitly turned on in a config file, and Odysseus talks to it exclusively over JSON, so the stock image is useless without that edit. And the upstream container image is built for a workstation: it carries a compiler toolchain for building llama.cpp, a full Chromium install, and a Docker client for driving the host daemon, none of which can function on a hosting platform.

This template resolves both. The search engine runs from an image with the JSON config baked in, and the app runs from an image rebuilt from a pinned upstream commit with the workstation tooling stripped out, taking it from roughly 3 GB down to under 800 MB without losing a single feature that would work on Railway anyway.

Common Use Cases

A private replacement for a hosted AI chat subscription, where the conversation history, uploaded documents and notes live on infrastructure you control rather than a vendor's.
Multi-step research with sources, run through a search engine that does not profile you and does not need an API key.
A single workspace that keeps documents, email, notes, tasks and a calendar next to the assistant that acts on them, instead of scattered across five separate tools.

Dependencies for Odysseus Hosting

Chroma, the vector store behind retrieval, semantic memory and tool selection. Runs privately with its own persistent volume.
SearXNG, a private metasearch engine, and the app's default search provider. Runs privately, with its JSON API enabled.
A persistent volume for the app's database, credentials, settings, uploads and generated files.
A model provider, which you supply after deploying. Odysseus speaks to OpenAI-compatible endpoints, so a hosted API key, a proxy, or your own machine running Ollama all work.

Deployment Dependencies

Odysseus source: https://github.com/odysseus-dev/odysseus
Setup guide: https://github.com/odysseus-dev/odysseus/blob/main/docs/setup.md
Images and build sheet for this template: https://github.com/hmseeb/odysseus-railway
SearXNG: https://github.com/searxng/searxng
Chroma: https://github.com/chroma-core/chroma

Implementation Details

Your first login. The deploy generates a random admin password. Open the odysseus service in your Railway project, go to Variables, and copy ODYSSEUS_ADMIN_PASSWORD. Sign in at your public URL as admin with that value. It is read exactly once, on the very first boot, to create the account. Editing it later has no effect. Change your password inside the app afterwards.

Connecting a model. Nothing is wired to an AI provider out of the box, because the right choice depends on you. Set one up inside the app under settings. Nothing needs redeploying. Notes, tasks, calendar, documents and email all work before you do this.

Expected first boot. The app creates its database, directories and admin account before it starts answering, so give the first deploy a couple of minutes. The embedding model downloads the first time retrieval is used, not at startup, and lands on the volume so it is not fetched again on later deploys.

Locking it down. The instance is on a public URL from the first second. Change the seeded password after logging in. Leave AUTH_ENABLED at true and LOCALHOST_BYPASS at false; either one flipped opens the workspace to anyone with the link. Signups are off by default.

Optional extras, all addable later. Email needs IMAP and SMTP details from your provider, entered in the app. A different search provider (Brave, Google, Tavily, Serper) is selectable in the app if you have a key. Calendar sync points at any CalDAV server. If you add a custom domain, update ALLOWED_ORIGINS on the odysseus service to match it, including the https:// prefix, or the browser will block the app's own requests.

Your data. Everything the app owns lives on one volume at /app/data: the database, your login, settings, uploads, notes, generated images and the search indexes. The vector store keeps a second volume. Back up by snapshotting both.

Troubleshooting. Empty web search results almost always mean the searxng service failed to deploy rather than a bug in the app, because the workspace reaches it privately and treats an unreachable engine as zero results. The same applies to chromadb and retrieval, which silently falls back to keyword matching. Login attempts are rate limited to 15 a minute across the whole instance rather than per person, since behind Railway's proxy every request appears to come from one address; a lockout clears itself within a minute.

Deliberately left out. Local model serving, which needs a GPU and a Docker socket on the host. GPU image upscaling, for the same reason. A push notification container, because notifications are a configurable integration that works fine against any hosted endpoint and would otherwise add a fourth service to your bill.

Scaling. One instance only. State is a SQLite database on a single volume, so the service cannot run multiple replicas. Vertical scaling is the path if you need more headroom.

Why Deploy Odysseus on Railway?

Railway gives this stack the three things it needs and a laptop does not: a private network so the vector store and the search engine are reachable by the app and by nobody else, persistent volumes that survive redeploys, and a public HTTPS address without touching a reverse proxy or a certificate.

The alternative is a machine you keep alive yourself, a compose file with four containers, a tunnel or port forward to reach it from your phone, and TLS you renew by hand. Here it is one deploy, and the parts that usually go wrong, enabling the search engine's JSON API and pointing the app at the right vector store host, are already wired up.

Odysseus is licensed AGPL-3.0-or-later. This template is not affiliated with the upstream project.