Deploy and Host gcli2api on Railway

Converting gcli2api to API interfaces allows developers and applications to access OpenAI, Gemini, and Claude compatible endpoints powered by underlying GeminiCLI and Antigravity authentications. gcli2api includes a full-featured web management console for managing OAuth credentials, monitoring usage, streaming logs, and configuring multi-account rotational routing for high-throughput AI API requests.

About Hosting gcli2api

Hosting gcli2api on Railway provisions a continuous containerized service running the FastAPI web server engine. Railway handles build execution, automated domain mapping with HTTPS encryption, and background container health management.

By default, gcli2api utilizes an embedded SQLite database and local file paths to manage credential states and refresh tokens. Railay simplifies this setup by attaching a persistent Railway Volume mounted to /app/creds, ensuring OAuth authorization tokens remain intact across service restarts and deployments. Alternatively, gcli2api can connect to a managed Railway MongoDB database service to store credentials in a cloud environment. Railway's networking layer routes public HTTPS requests on the target port directly to your container.

Common Use Cases

OpenAI & Claude API Proxy: Serve standardized OpenAI /v1/chat/completions and Claude /v1/messages API endpoints to third-party tools and clients using Gemini CLI capabilities.
Multi-Account OAuth Management: Authenticate multiple Google accounts via a Web Admin Panel to automatically rotate credentials and bypass rate limits.
Multimodal & Thinking Model Gateway: Enable support for structured reasoning models and image generation endpoints within standardized chat applications.

Dependencies for gcli2api Hosting

Deployment Dependencies

Implementation Details

Docker

gcli2api deploys using the official published container image:

ghcr.io/su-kaka/gcli2api:latest

If deploying directly from the source repository, Railway automatically detects the Dockerfile in the repository root and builds the container environment.

Public Networking

gcli2api requires public network access to expose the web configuration panel and client API endpoints.

Setting	Value
Proxy Type	HTTP Proxy
Target Port	`7861`

Environment Variables

Variable	Required	Description
`PORT`	Yes	Internal container port binding. Must be set to `7861`.
`HOST`	Yes	Network interface binding. Set to `0.0.0.0`.
`PASSWORD`	Yes (or use separated passwords)	Universal password for accessing both the Web Panel and API endpoints.
`API_PASSWORD`	Optional	Independent access password specifically for chat API endpoints.
`PANEL_PASSWORD`	Optional	Independent access password specifically for Web Admin Panel access.
`MONGODB_URI`	Optional	Connection string for cloud storage (e.g., `${{MongoDB.MONGO_URL}}`).
`MONGODB_DATABASE`	Optional	Database name when using MongoDB storage (Default: `gcli2api`).
`RETRY_429_ENABLED`	Optional	Automatically retry requests on rate limit errors (Default: `true`).
`RETRY_429_MAX_RETRIES`	Optional	Maximum retry count for 429 errors (Default: `3`).
`RETRY_429_INTERVAL`	Optional	Retry interval in seconds (Default: `1.0`).
`ANTI_TRUNCATION_MAX_ATTEMPTS`	Optional	Maximum retry attempts for anti-truncation mode (Default: `3`).
`AUTO_BAN`	Optional	Automatically disable failing credentials (Default: `true`).
`COMPATIBILITY_MODE`	Optional	Convert system messages to user messages for client compatibility (Default: `false`).
`LOG_LEVEL`	Optional	Application logging verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`).
`PROXY`	Optional	HTTP/HTTPS proxy address for outgoing API requests.

Environment Variables (Raw Editor)

PORT=7861
HOST=0.0.0.0
PASSWORD=your_secure_password
RETRY_429_ENABLED=true
RETRY_429_MAX_RETRIES=3
RETRY_429_INTERVAL=1.0
AUTO_BAN=true
COMPATIBILITY_MODE=false
LOG_LEVEL=INFO

Persistent Storage

Persistent storage is required when using the default local SQLite database to prevent loss of OAuth refresh tokens during container restarts.

To attach persistent storage in Railway:

Open your gcli2api Service in Railway.
Select Settings $\rightarrow$ Volumes.
Click Add Volume.
Set the Mount Path:

/app/creds

Note: If MONGODB_URI is configured, application state is stored in MongoDB, but mounting /app/creds remains recommended for local credential caching.

Database

If using external cloud database storage instead of the default SQLite local volume:

Add a MongoDB service to your Railway project.
Add the MONGODB_URI environment variable to the gcli2api service, referencing the Railway MongoDB connection string:

MONGODB_URI=${{MongoDB.MONGO_URL}}
MONGODB_DATABASE=gcli2api

Build & Start

No custom build or start commands are required. The application automatically starts via the default container entrypoint command (python web.py).

Accessing the Application

In Railway, navigate to Service Settings $\rightarrow$ Networking $\rightarrow$ Public Networking.
Click Generate Domain to get a public endpoint URL (e.g., [https://gcli2api-production.up.railway.app](https://gcli2api-production.up.railway.app)).
Open the domain in your browser to access the Web Admin Panel.
Log in using the configured PASSWORD (or PANEL_PASSWORD).
Complete the Google OAuth authentication flow inside the panel to add API credentials.
Configure your AI client using your domain URL and your API password as the Bearer token:

OpenAI Endpoint: https:///v1/chat/completions
Gemini Endpoint: https:///v1/models
Claude Endpoint: https:///v1/messages

Why Deploy gcli2api on Railway?

Railway provides a seamless, developer-first platform for deploying production applications. With instant Git deployments, automatic HTTPS provisioning, built-in metrics, and isolated environment variables, Railway handles infrastructure complexity so you can focus on building your application.