Deploy and Host Onyx Lite on Railway

Onyx is an open-source AI chat platform that works with any LLM. Onyx Lite is its official minimal deployment: the full chat experience (agents, Projects, file uploads, tools and MCP) on PostgreSQL alone, without the search index, Redis, object storage and model servers that the full stack needs.

About Hosting Onyx Lite

This template follows upstream's docker-compose.onyx-lite.yml: DISABLE_VECTOR_DB=true, with the cache, login sessions and uploaded files moved into Postgres. Four services run: a Caddy front door (the only public one), the Next.js web server, the FastAPI API server and Postgres.

On the first boot the API server applies Onyx's database migrations, then creates your admin account from ADMIN_EMAIL and a generated ADMIN_PASSWORD, and makes sign-up invite-only. Nobody who finds the URL can claim the instance or register uninvited. Until the API answers, the front door shows a "starting" page instead of an error.

Common Use Cases

A shared ChatGPT-style workspace for a team, on your own OpenAI, Anthropic, Gemini, Bedrock or Azure keys
One front door for many models, including Ollama or a LiteLLM gateway running in the same Railway project
Reusable agents with their own prompts, tools and MCP servers, plus chat over files uploaded to a chat or a Project

Dependencies for Onyx Lite Hosting

Your email address, asked at deploy. It becomes the admin login.
An API key for at least one LLM provider, added after you sign in (Admin Panel > Language Models). Onyx boots without one.
Postgres, included. In Lite mode it holds everything: accounts, chats, cache, sessions and uploaded files.

Deployment Dependencies

Onyx Lite documentation
Upstream Lite overlay (v4.8.1)
Onyx on GitHub
Images: onyxdotapp/onyx-backend:v4.8.1, onyxdotapp/onyx-web-server:v4.8.1, caddy:2.11-alpine, Railway Postgres 18

Implementation Details

First sign-in. Open the public URL of the Onyx service and sign in with ADMIN_EMAIL and ADMIN_PASSWORD (api-server > Variables). The password is only read on the first boot; change it in Onyx afterwards. Then add a model under Admin Panel > Language Models.

Inviting people. Admin Panel > Users > Invite Users. No mail server is needed: invited addresses can create their account on the sign-up page. To open sign-up to anyone instead, turn off Admin Panel > Security & Hardening > Restrict Open Sign-Up.

What Lite leaves out. Connectors (Slack, Drive, Confluence and the rest), RAG search over indexed documents, and Onyx Craft. The code interpreter tool is also unavailable: it runs code in containers it starts through a Docker socket, which Railway does not provide. If you need connectors, deploy the full Onyx stack instead.

Routing. Caddy mirrors upstream's nginx config: /api/* goes to api-server with the prefix stripped, /openapi.json, /auth/saml/* and /scim/* go to api-server unchanged, and everything else goes to web-server. Caddy resolves the private hostnames per connection, so redeploys never leave it pointing at a stale address, and it trusts Railway's edge so X-Forwarded-Proto: https reaches Onyx.

Details that matter. WEB_DOMAIN is set on the web server as well as the API: the web server builds SSO callback redirects from it, and without it they point at https://0.0.0.0:3000. The API's two connection pools are sized to fit the 100-connection default of Railway's Postgres. api-server and web-server have healthchecks, so redeploys switch over without downtime.

Upgrading. Change the image tag on api-server and web-server together; migrations run on the next boot.

Why Deploy Onyx Lite on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Onyx Lite on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.