Agent OS Railway

Welcome to Agent OS Railway: a robust, production-ready application for serving Agentic Applications as an API on Railway. It includes:

• An AgentOS instance: An API-based interface for production-ready Agentic Applications.
• A PostgreSQL database for storing Agent sessions, knowledge, and memories.
• A set of pre-built Agents, Teams and Workflows to use as a starting point.

For more information, checkout Agno and give it a ⭐️

Quickstart

Follow these steps to get your Agent OS up and running:

Get Docker Desktop should be installed and running. Get OpenAI API key

Clone the repo

git clone https://github.com/agno-agi/agent-infra-railway.git
cd agent-infra-railway

Configure API keys

We use GPT 5 as the default model, please export the OPENAI_API_KEY environment variable to get started.

export OPENAI_API_KEY="YOUR_API_KEY_HERE"

Note: You can use any model provider, just update the respective agents, teams and workflows and add the required library in the pyproject.toml and requirements.txt file.

Running the application

The application can be run on two environments:

Locally using Docker Compose or on Railway using the Railway CLI.

Locally using Docker Compose

Run the application using docker compose (Remove the --build flag if you already have the image built):

docker compose up -d --build

This command starts:

• The AgentOS instance, which is a FastAPI server, running on http://localhost:8000.
• The PostgreSQL database, accessible on localhost:5432.

Once started, you can:

• Test the API at http://localhost:8000/docs.

Connect to AgentOS UI

• Open the Agno AgentOS UI.
• Connect your OS with http://localhost:8000 as the endpoint. You can name it AgentOS (or any name you prefer).
• Explore all the features of AgentOS or go straight to the Chat page to interact with your Agents, Teams and Workflows.

Stop the application

When you're done, stop the application using:

docker compose down

Railway Deployment

To deploy the application on Railway, please follow the steps below:

1. Install the Railway CLI (More details here):

brew install railway

2. Login to your Railway account:

railway login

Note: Remember to either export the OPENAI_API_KEY environment variable.

3. Run the deployment script:

./scripts/railway_up.sh

4. Monitor the deployment (Optional):

railway logs --service agent_os

5. Access the application via the Railway UI:

railway open

6. In the CLI, you will see the domain of your application. Click on it to access your AgentOS FastAPI server. You can navigate to <railway-domain>/docs to access the API documentation.

7. On Agno AgentOS UI, connect your OS with the domain you just created.

• Open the Agno AgentOS UI.
• Connect your OS with <railway-domain> as the endpoint.

Congratulations! You have successfully deployed Agent OS on Railway. Your OS is now live and ready to use. You can now start using your Agents, Teams and Workflows as well as take a look at your Sessions, Memories, Knowledge and Metrics.

Updating your Railway Deployment

To update your Railway deployment, you can run the following command after making changes to the application:

railway up --service agent_os -d

This will trigger a new deployment of your application by creating a new docker image and deploying it to Railway.

Stopping your Railway Deployment

To stop your Railway deployment, you can run the following command:

railway down --service agent_os
railway down --service pgvector

This will stop your services on Railway.

Note: In order to start services again, in the same project on railway, you can run the ./scripts/railway_up.sh script again but make sure to remove the railway init command as that will create a new project on Railway.

What the railway_up.sh script does:

The script does the following:

1. Initializes a new project on Railway
2. Deploys PgVector database on Railway
3. Creates the application service with environment variables already set (DB_DRIVER, DB_USER, DB_PASS, DB_HOST, DB_PORT, DB_DATABASE, OPENAI_API_KEY)
4. Deploys the application
5. Creates a domain for your application

Prebuilt Agents, Teams and Workflows

The /agents folder contains pre-built agents, teams and workflows that you can use as a starting point.

#TODO: Add documentation for agents, teams and workflows

Create Virtual Environment & Install Dependencies

Run the dev_setup.sh script. This will create a virtual environment and install project dependencies:

./scripts/dev_setup.sh

Activate Virtual Environment

Activate the created virtual environment:

source .venv/bin/activate

(On Windows, the command might differ, e.g., .venv\Scripts\activate)

Managing Python Dependencies

If you need to add or update python dependencies:

Modify pyproject.toml

Add or update your desired Python package dependencies in the [dependencies] section of the pyproject.toml file.

Generate requirements.txt

The requirements.txt file is used to build the application image. After modifying pyproject.toml, regenerate requirements.txt using:

./scripts/generate_requirements.sh

To upgrade all existing dependencies to their latest compatible versions, run:

./scripts/generate_requirements.sh upgrade

Rebuild Docker Images

Rebuild your Docker images to include the updated dependencies:

docker compose up -d --build

Running Tests

This project comes with a set of integration tests that you can use to ensure the application is working as expected.

First, start the application:

docker compose up -d

Then, run the tests:

pytest tests/

Then close the application again:

docker compose down

Community & Support

Need help, have a question, or want to connect with the community?

• 📚 Read the Agno Docs for more in-depth information.
• 💬 Chat with us on Discord for live discussions.
• ❓ Ask a question on Discourse for community support.
• 🐛 Report an Issue on GitHub if you find a bug or have a feature request.