Deploy Agno

Deploy and Host Agno AgentOS on Railway

Agno AgentOS is a production-ready runtime for building, serving, and managing AI agent platforms.

This Railway template deploys AgentOS with PostgreSQL, giving you persistent sessions, memory, knowledge, traces, REST APIs, MCP connectivity, scheduling, observability, and secure production deployment.

About Hosting Agno AgentOS

AgentOS is the runtime layer of the Agno ecosystem. It allows you to build AI agents using the Agno SDK, expose them through production APIs, connect them to external interfaces, and manage runtime state using your own infrastructure.

This template uses PostgreSQL as the persistent storage backend for AgentOS data such as:

• Sessions
• Memory
• Knowledge
• Traces
• Runtime state
• Agent activity

The AgentOS service is publicly accessible, while PostgreSQL communicates only through Railway private networking.

Included Services

• Agno AgentOS — Agent runtime, REST API, MCP server, scheduling, observability
• PostgreSQL — Persistent storage for AgentOS data and traces
• Railway Private Networking — Secure internal communication between AgentOS and PostgreSQL

Common Use Cases

• Build and host AI agents
• Expose agents through REST APIs
• Run multi-agent applications
• Store persistent agent memory
• Track sessions and execution traces
• Build agent-powered backend services
• Connect agents to MCP-compatible clients
• Add human approval to agent workflows
• Run scheduled agent jobs
• Build internal AI platforms
• Integrate agents with external tools and services
• Deploy agent applications without managing your own server infrastructure

Dependencies for Agno AgentOS Hosting

This template includes:

• Agno AgentOS
• PostgreSQL

Redis is not required for the standard AgentOS deployment.

PostgreSQL is used as the primary persistent storage layer for sessions, memory, knowledge, traces, and other runtime data.

AgentOS API

AgentOS runs on port:

8000

After deployment, generate a public domain for the AgentOS service.

A typical deployment URL looks like:

https://your-agentos-domain.up.railway.app

Interactive API documentation is available at:

https://your-agentos-domain.up.railway.app/docs

MCP Endpoint

AgentOS can expose agents and tools through Model Context Protocol.

The MCP endpoint is available at:

https://your-agentos-domain.up.railway.app/mcp

This allows compatible clients to connect to your AgentOS deployment.

Potential integrations include:

• ChatGPT
• Claude
• Claude Code
• Codex
• Cursor
• Other MCP-compatible applications

PostgreSQL Storage

PostgreSQL runs as a private internal service.

AgentOS connects to PostgreSQL using Railway service references.

The database stores persistent AgentOS data including:

• Agent sessions
• Memory
• Knowledge
• Traces
• Runtime metadata

The PostgreSQL service does not need a public domain.

Persistent storage is handled by the PostgreSQL Railway Volume.

Important Environment Variables

AgentOS

OPENAI_API_KEY

API key used by the default OpenAI-based agents and embeddings.

Users can replace the default agent configuration with other supported model providers if required.

RUNTIME_ENV

Controls the AgentOS runtime environment.

This template is intended to run with:

prd

for production deployments.

AGENTOS_URL

Public URL of the deployed AgentOS service.

The template references the generated Railway public domain automatically.

JWT_VERIFICATION_KEY

Public verification key used by AgentOS production authentication.

This value must be configured after connecting the deployment to the AgentOS Control Plane.

MCP_CONNECT_SECRET

Optional secret used for external MCP client connectivity.

PARALLEL_API_KEY

Optional API key used for web search and faster knowledge ingestion.

AGNO_TELEMETRY

Optional setting that controls anonymous Agno telemetry.

PostgreSQL Connection

AgentOS connects to PostgreSQL using:

• DB_HOST
• DB_PORT
• DB_USER
• DB_PASS
• DB_DATABASE
• DB_DRIVER

These values reference the PostgreSQL Railway service directly.

The expected database driver is:

postgresql+psycopg

Production Authentication Setup

AgentOS production mode requires authentication configuration.

After the first deployment:

1. Generate a public domain for the AgentOS service.
2. Open the AgentOS Control Plane.
3. Connect your deployed AgentOS instance.
4. Enable token-based authorization.
5. Copy the generated public JWT verification key.
6. Add the value to:

JWT_VERIFICATION_KEY

7. Redeploy the AgentOS service.

This step is important because production mode is designed to reject unsecured traffic when JWT verification is not configured.

Networking

The intended Railway architecture is:

Internet
   │
   ▼
Railway HTTPS
   │
   ▼
Agno AgentOS
    :8000
      │
      │ Railway Private Network
      ▼
 PostgreSQL
    :5432

Only AgentOS should be exposed publicly.

PostgreSQL should remain private.

Persistent Storage

The AgentOS application service does not require its own persistent volume.

Persistent application data is stored in PostgreSQL.

The recommended persistence model is:

AgentOS
   │
   ▼
PostgreSQL
   │
   ▼
Railway Volume

This keeps the AgentOS runtime stateless and makes redeployments easier.

After Deployment

1. Wait for AgentOS and PostgreSQL to become healthy.
2. Generate a public domain for AgentOS on port 8000.
3. Keep PostgreSQL private.
4. Verify the AgentOS /docs endpoint.
5. Connect the deployment to the AgentOS Control Plane.
6. Configure JWT_VERIFICATION_KEY.
7. Redeploy AgentOS.
8. Configure the required model provider API key.
9. Test your first agent request.
10. Configure MCP connectivity if required.
11. Review sessions, traces, memory, and agent activity from the AgentOS platform.

Security Notice

For production deployments:

• Keep PostgreSQL private
• Protect all model provider API keys
• Use production authentication
• Configure JWT_VERIFICATION_KEY
• Do not run public production deployments with unsecured development settings
• Rotate exposed credentials immediately
• Use scoped access tokens where possible
• Review MCP connectivity before exposing external tools

Agno AgentOS vs Alternatives

Agno AgentOS is particularly useful when you want a complete agent runtime with persistent storage, production APIs, MCP support, observability, and infrastructure ownership.

Why Deploy Agno AgentOS 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.

Deploying Agno AgentOS on Railway provides:

• Automatic HTTPS domains
• Private PostgreSQL networking
• Persistent agent data
• Simple environment variable management
• Easy redeployments and upgrades
• Integrated logs and monitoring
• Production-ready REST APIs
• MCP connectivity
• Agent memory and knowledge storage
• A clean two-service architecture

This template provides a practical way to run your own AgentOS deployment with persistent PostgreSQL storage and production-focused infrastructure.