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; until it answers, the front door shows a 'starting' page. Then open the URL and create your account: the first account on a new instance becomes the admin, so do it as soon as the deploy finishes.

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

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 Caddy service. A new instance goes straight to sign-up, and the first account becomes the admin. Then add a model under Admin Panel > Language Models.

Inviting people. After the first account, anyone with the URL can sign up. To make it invite-only, turn on Admin Panel > Security & Hardening > Restrict Open Sign-Up, then add people under Admin Panel > Users > Invite Users (no mail server needed).

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.