Deploy and Host MetApi on Railway

MetApi is an open-source AI gateway and model aggregation platform that unifies multiple AI providers and API gateways behind a single OpenAI-compatible endpoint. It provides intelligent model routing, centralized account management, automatic failover, balance monitoring, scheduled check-ins, and a web dashboard for managing AI infrastructure from one place.

About Hosting MetApi

Hosting MetApi on Railway provides a production-ready environment for running your own AI aggregation gateway without managing servers. Railway can deploy the official Docker image, automatically provision networking, and expose the application over HTTPS with a public domain.

MetApi stores its configuration, routing rules, credentials, logs, and SQLite database locally, making a Railway Volume essential for persistent storage. While SQLite is the default database, MySQL and PostgreSQL are also supported for external deployments. Railway Variables simplify secret management for administrator authentication, proxy access, scheduled jobs, and notification services, allowing you to securely operate a centralized AI gateway with minimal infrastructure management.

Common Use Cases

Centralize multiple AI providers behind a single OpenAI-compatible API
Intelligent routing and failover across AI gateway services
Monitor balances, models, and API usage from a unified dashboard

Dependencies for MetApi Hosting

Dependency	Required	Purpose
Railway Volume	Yes	Stores the SQLite database, encrypted credentials, logs, and runtime data
SQLite	Yes (default)	Default application database
MySQL or PostgreSQL	Optional	External database backend
Docker Image	Yes	Deploys the MetApi application

Deployment Dependencies

Resource	Link
GitHub Repository	https://github.com/cita-777/metapi
Docker Hub	https://hub.docker.com/r/1467078763/metapi

Implementation Details

Docker

MetApi provides an official Docker image:

1467078763/metapi:latest

Railway deploys the official Docker image directly, so no custom build or start commands are required.

Public Networking

Setting	Value
Proxy Type	HTTP Proxy
Target Port	`4000`

Generate a Railway domain from Settings → Networking → Generate Domain after deployment.

Environment Variables

Important

AUTH_TOKEN is required for your first login.

After deployment, sign in to the dashboard using the value configured for AUTH_TOKEN. Replace the default change-me-admin-token before deploying to production.

Variable	Required	Description
`AUTH_TOKEN`	Yes	Administrator login token used for the initial dashboard login.
`PROXY_TOKEN`	Yes	Bearer token used by downstream `/v1/*` proxy requests.
`ACCOUNT_CREDENTIAL_SECRET`	Yes (Production)	Encryption key for stored credentials. Generate a unique 32+ byte random secret and do not reuse `AUTH_TOKEN`.
`PORT`	Yes	Internal application listening port. Use `4000`.
`DATA_DIR`	Yes	Directory used for persistent application data.
`TZ`	No	Time zone for scheduled jobs and logs.
`CHECKIN_CRON`	No	Schedule for automatic daily check-ins.
`BALANCE_REFRESH_CRON`	No	Schedule for automatic balance refresh.
`WEBHOOK_URL`	No	Webhook notification endpoint.
`BARK_URL`	No	Bark notification URL.
`SERVERCHAN_KEY`	No	ServerChan notification key.
`TELEGRAM_ENABLED`	No	Enable Telegram notifications.
`TELEGRAM_BOT_TOKEN`	No	Telegram bot token.
`TELEGRAM_CHAT_ID`	No	Telegram chat ID.

Raw Editor example:

AUTH_TOKEN=your-secure-admin-token
PROXY_TOKEN=your-secure-proxy-token
ACCOUNT_CREDENTIAL_SECRET=your-32-byte-random-secret

PORT=4000
DATA_DIR=/app/data
TZ=UTC

CHECKIN_CRON=0 8 * * *
BALANCE_REFRESH_CRON=0 * * * *

Persistent Storage

A Railway Volume is required.

Open your Railway service and navigate to:

Settings → Volumes → Add Volume

Mount the volume at:

/app/data

Configure:

DATA_DIR=/app/data

This directory stores the SQLite database, encrypted credentials, routing configuration, logs, and runtime data. Without a Railway Volume, this data will be lost when the container is recreated.

Database

MetApi uses SQLite by default and requires no additional database service.

If preferred, you can deploy a Railway MySQL or PostgreSQL service and configure the appropriate database connection variables according to the project's documentation.

Build & Start

The official Docker image contains everything required to run MetApi.

No custom build or start commands are required.

Accessing the Application

After deployment:

Open your Railway service.
Navigate to Settings → Networking.
Click Generate Domain.
Open the generated Railway URL.

First Login

Use the value of AUTH_TOKEN as the administrator login token.

For example:

AUTH_TOKEN=my-secure-admin-token

my-secure-admin-token

If you later change the administrator token from the MetApi Settings page, use the updated token for all future logins.

Why Deploy MetApi 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 MetApi 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.