Setup

Run Starter Template locally in five minutes.

This page gets Starter Template running on your machine with a local Postgres, the Knowledge Agent loaded with the Agno docs, and the MCP Agent connected to the Agno docs MCP.

Prerequisites

• Docker Desktop (install)
• OpenAI API key (get one)

Manual

1. Clone and configure

   git clone https://github.com/agno-agi/agentos-railway-template.git agentos-railway
   cd agentos-railway
   cp example.env .env
   

   Open .env and set OPENAI_API_KEY. Everything else has sensible defaults.

2. Start AgentOS

   docker compose up -d --build
   

   First run pulls the base image, builds the container, and starts Postgres alongside the app. Takes a minute or two. Subsequent starts are instant.

3. Load the Knowledge Agent

   docker exec -it agentos-api python -m agents.knowledge_agent
   

   This loads the default documents (Agno Introduction + First Agent) into the pgvector index. Skip this step and the Knowledge Agent has nothing to search.

4. Verify it's running

   curl http://localhost:8000/health
   

   Expect {"status":"ok"}. Connection refused means the container is still starting. Check docker compose logs -f agentos-api and wait for the Agno banner.

Agentic

If you have a coding agent like Claude Code or Codex, paste this prompt into a fresh session in an empty directory. The agent clones the repo, starts AgentOS, loads the knowledge base, and verifies it’s running.

The prompt below never asks the agent to read or transmit your API key. The agent opens .env for you to edit, then waits for you to confirm before continuing.

Set up the Agno Starter template locally for me.

Steps:
1. Clone https://github.com/agno-agi/agentos-railway-template.git into the current directory as agentos-railway and cd into it.
2. Copy example.env to .env. Open .env in the user's editor (or print the path and tell them to open it). Tell the user: "Set OPENAI_API_KEY in .env, save the file, then tell me to continue." Wait for confirmation before proceeding. Do not ask the user to paste the key into this chat. Do not read the key from .env or print its value at any point.
3. Check that Docker Desktop is running (`docker info`). If not, tell me to start it and stop.
4. Run `docker compose up -d --build`. Stream the output so I can see progress.
5. Poll `curl -s http://localhost:8000/health` every 3 seconds for up to 60 seconds. Proceed once it returns `{"status":"ok"}`.
6. Run `docker exec -it agentos-api python -m agents.knowledge_agent` to load the default knowledge base. Show me the output.
7. Print next steps: open os.agno.com, Add OS → Local → http://localhost:8000.

If any step fails, stop and show me the error. Don't try to fix it on your own.

Connect to AgentOS UI

Open os.agno.com and log in.

Click Add OS, choose Local, enter http://localhost:8000, click Connect.

Try one prompt against each agent:

“What is Agno?” → Knowledge Agent answers from the loaded RAG corpus.

“How do I create my first agent?” → Knowledge Agent cites the First Agent doc.

“Search the Agno docs for how to use LearningMachine.” → MCP Agent calls the docs MCP.

“What tools do you have access to?” → MCP Agent lists every tool the docs MCP exposes.

What you have now

Agent	Tools	Backed by
Knowledge Agent	search_knowledge_base, agentic memory	pgvector index seeded with https://docs.agno.com/introduction.md and https://docs.agno.com/first-agent.md
MCP Agent	Whatever the docs MCP exposes	MCPTools(url="https://docs.agno.com/mcp")

Both agents share the same Postgres for sessions and memory.

Add your own knowledge

Edit agents/knowledge_agent.py and update load_default_documents() to point at your own URLs or files:

def load_default_documents() -> None:
    knowledge.insert(
        name="Your Company Handbook",
        url="https://example.com/handbook.md",
        skip_if_exists=True,
    )

Then re-run the loader:

docker exec -it agentos-api python -m agents.knowledge_agent

The new documents land in the same pgvector index. skip_if_exists=True makes the loader idempotent.

Next

Deploy to Railway →