# FastAPI for Agents > Source: > Published: 2026-07-15 21:49:01+00:00 AgentOS turns your agents into a production API: 80+ endpoints for runs, sessions, memory, knowledge, and evals. Build your product on top of it, connect your agents to AI apps like Claude and ChatGPT, and chat interfaces like Slack, WhatsApp, Telegram, and Discord. AgentOS gives you one AI backend for every frontend: **Your product.** Call the REST API from your app: run agents, stream responses, and manage sessions, memory, and knowledge.**AgentOS UI.** Chat with agents, build new ones with AgentOS Studio, and inspect sessions, traces, memory, and evals from the AgentOS UI at[os.agno.com](https://os.agno.com?utm_source=github&utm_medium=example-repo&utm_campaign=agentos-railway&utm_content=agentos-railway&utm_term=railway).**Coding agents.** Manage the full agent development lifecycle (create, extend, improve, eval and review) using the skills in.`.agents/skills/` **AI apps.** MCP clients like Claude and ChatGPT can use your agents through the MCP server at`/mcp` .**Chat interfaces.** Chat with your agents from Slack, WhatsApp, Telegram, and Discord. Built on [Agno](https://docs.agno.com). Everything runs in your cloud, your data lives in your database. This codebase comes with: **Two platform agents** that help you build and run the platform from your favorite AI apps like Claude and ChatGPT.**Agent Builder** creates agents, teams, and workflows using the AgentOS Studio.**Platform Manager** understands, monitors, and explains the platform: codebase questions, eval history, deployment checks, schedules.**Coding-agent skills** let Claude Code, Codex, Cursor, and other coding agents build, test, and improve the platform automatically — see[Using the platform](#using-the-platform). Trace data, agent code, evals, and system logs are all available to coding agents, so the platform can inspect and improve itself end to end. The fastest way to get started is using a coding agent. Copy the prompt below into Claude Code, Cursor or Codex and it'll take you from zero to a running platform. ``` Help me set up AgentOS on this machine. Be self-driving: anything you can do — open a file, open a URL, launch an app — do it. Stop when you need a human: typing a secret, installing software, signing in to a website. When you do stop, tell me exactly what to do. Never read or print secrets. 1. Clone https://github.com/agno-agi/agentos-railway.git into a folder called agent-platform and cd in. Then read AGENTS.md end to end — it is the source of truth for how this platform works and answers most questions you'll hit along the way. 2. Confirm Docker is installed and running (`docker info` succeeds). If it's installed but not running, start it (`open -a Docker` on macOS) and poll until it's up. Stop for me only if Docker isn't installed — then give me steps to install Docker Desktop and wait. 3. Set up my environment. Run `cp example.env .env`, then help me set my OPENAI_API_KEY. If it's already set in my shell, tell me you found one and offer to copy it in — move the value across without reading or printing it. Otherwise open .env in my editor (cursor, code etc.) and ask me to paste the key. Never open a terminal editor like vim or nano from your own shell — it will hang this session. 4. Start the platform with `docker compose up -d --build`, then poll http://localhost:8000/docs until it returns 200 (first build takes a few minutes). If it never comes up, read `docker compose logs agentos-api` and fix what you find. 5. Prove it end to end with ./scripts/mcp_check.sh — it should print "MCP OK" and a real agent answer. Show me that answer: it's my platform talking. 6. Next, help me set up the AgentOS UI. Ask if you can open https://os.agno.com and walk me through the connection process: Connect OS → enter http://localhost:8000 → name it "Local AgentOS". That's where I chat with my agents and inspect sessions, memory, and evals. 7. Finish with a short summary and what I should do next: run /create-new-agent right here and you'll build a new agent with me, then /improve-agent to sharpen it — that loop is yours to keep. Mention in one line that I can also connect my platform to coding agents (like yourself) using `uvx agno connect`, and to claude.ai / ChatGPT over OAuth once it's deployed to production. ``` Prerequisite:[Docker]installed and running. ``` git clone https://github.com/agno-agi/agentos-railway.git agentos cd agentos # Configure credentials cp example.env .env # Open .env and set OPENAI_API_KEY # Run the platform on docker docker compose up -d --build ``` Confirm your AgentOS is running at [http://localhost:8000/docs](http://localhost:8000/docs). - Open [os.agno.com](https://os.agno.com?utm_source=github&utm_medium=example-repo&utm_campaign=agentos-railway&utm_content=agentos-railway&utm_term=railway)and sign in. - Click **Connect OS**, enter`http://localhost:8000` as the URL, name it**Local AgentOS**, and connect. - Click **Chat** under the**Agent Builder** agent and try the first prompt: "Build an agent that tracks AI news and writes a daily brief". Go through the agent development process. - Once created, click the **Refresh** button on the top right. You should now see the "Daily AI News Brief" agent in the**Agents** dropdown. Click the newly created agent. - Ask: "What's new with Anthropic?" Click **Chat** under **Platform Manager** and ask: "How healthy is the platform?" It answers from the codebase and runtime data — eval history, deployment checks, schedules, and the component you just built. You can run the platform anywhere that supports containerized images. This codebase comes with scripts to deploy the platform to [Railway](https://railway.com). Prerequisite:[Railway CLI]installed and`railway login` completed. Create a new `.env.production` file for production credentials. ``` cp .env .env.production # or cp example.env .env.production # Edit .env.production with production values ``` Keeping a separate `.env.production` lets us use different values for local and production: different OpenAI keys, production-only credentials, a different Slack workspace. ``` ./scripts/railway/up.sh ``` This provisions the AgentOS service and Postgres on the same private network. The script pauses and asks for a JWT verification key for authentication (see next section). Token-Based Authorization is on by default. Without a `JWT_VERIFICATION_KEY` or `JWT_JWKS_FILE` , the app refuses to serve traffic in production. The platform's job is to keep your data private, so the safe default is "refuse to start" without an authentication token. Token-Based Auth gives you three things: **No public access.** The server rejects requests without a valid token.**Per-request identity.** Middleware parses the token and extracts the`user_id` ,`session_id` , and custom claims. Each request is tied to a user and session, giving you auditability and traceability.**Granular permissions.** User tokens can run an agent and view their own sessions. Admin tokens read everyone's sessions and test any agent. During `./scripts/railway/up.sh` , the script creates your Railway domain and pauses so you can mint the key before the app starts. - Open [os.agno.com](https://os.agno.com?utm_source=github&utm_medium=example-repo&utm_campaign=agentos-railway&utm_content=agentos-railway&utm_term=railway), click**Connect OS**→** Live**, enter your Railway domain, and connect. - Name it **Live AgentOS**. - Go to **Settings**→** OS & Security**. - Turn **Token-Based Authorization (JWT)** on. - Copy the public key. - Paste the full public key into the `up.sh` prompt. The script saves it into your env file for future syncs: ``` JWT_VERIFICATION_KEY="-----BEGIN PUBLIC KEY----- MIIBIjANBgkq... -----END PUBLIC KEY-----" ``` Heads up.Live AgentOS Connections are a paid feature. Use`PLATFORM30` to get 1 month off. We are working on a free trial so you don't have to pay to try. If you get something wrong, you can re-sync environment variables with `./scripts/railway/env-sync.sh` . Re-run `uvx agno connect` , this time pointed at your deployed domain, to connect Claude Code, Claude Desktop, Codex, and Cursor to your production platform: ``` uvx agno connect --url https:// ``` For **claude.ai and ChatGPT (web)**: add `https:///mcp` as a custom connector in the chat app's connector settings. Leave the form's optional OAuth fields (client ID / client secret) empty. Click **Connect** and, on the consent page, enter the `MCP_CONNECT_SECRET` that `up.sh` generated during deploy (saved in `.env.production` ). You can check the logs on the Railway dashboard, or by running the following command: ``` railway logs --service agent-os ``` To redeploy your AgentOS, run the following command: ``` ./scripts/railway/redeploy.sh ``` Recommended: Auto-deploy on merge to `main` using: - Open the Railway dashboard, your project, the agent-os service, **Settings**. - Under **Source**, click** Connect Repo**and pick your repo. - Set the deploy branch to `main` and save. Push to `main` triggers a build and rolling deploy. `./scripts/railway/env-sync.sh` is still how you sync env changes. To re-sync environment variables, run the following command: ``` ./scripts/railway/env-sync.sh ./scripts/railway/down.sh ``` Deletes the Railway project: the agent-os service, the pgvector database, and its volume, **including all data**. It also removes the AGENTOS_URL from your env file so a future `up.sh` starts clean. Set `authorization=False` in [ app/main.py](/agno-agi/agentos-railway/blob/main/app/main.py) and redeploy. Use this only inside a private VPC behind another auth layer. Without it, anyone who guesses your Railway domain can access your platform. This platform is designed so that coding agents can drive the entire **create → improve → evaluate → maintain** lifecycle for you. Open your coding agent of choice (Claude Code, Codex, Cursor) and run: ``` /create-new-agent ``` It asks a few questions, generates the agent file in `agents/` , registers it in `app/main.py` , adds its description and quick prompts to `app/config.yaml` , restarts the container, and smoke-tests it live. Improve your agents by running the following skills: — Add a tool, add a capability, refine the instructions, fix a known bug.`/extend-agent` — Claude simulates scenarios from the agent's`/improve-agent` `INSTRUCTIONS` , runs them against the live container, judges the responses, and edits until they pass. Run the eval suite to check for regressions. The evals live in [ evals/cases.py](/agno-agi/agentos-railway/blob/main/evals/cases.py), and run history shows up at os.agno.com next to your sessions and traces. The evals run on the host machine, so set up the venv with `./scripts/venv_setup.sh && source .venv/bin/activate` , then: ``` python -m evals --tag smoke # fast checks of the self-driving surfaces python -m evals --tag release # broader pre-release confidence python -m evals --name # one case while iterating python -m evals -v # stream the full run with rich panels ``` If a case fails, run ** /eval-and-improve** — it diagnoses each failure, fixes what's in scope, and loops until green. Because the repo is managed by coding agents, it moves fast. Run `/review-and-improve` before a release or after a refactor: it sweeps for drift between docs, code, and config, auto-fixes mechanical drift like stale paths and missing env vars, and flags anything bigger. AgentOS comes with an MCP server at `/mcp` (enabled by setting `mcp_server=True` in [ app/main.py](/agno-agi/agentos-railway/blob/main/app/main.py)), so any MCP client can call your agents, teams, and workflows through tools like `run_agent` , `run_team` , and `run_workflow` .Register your AgentOS with the MCP clients on your machine: ``` uvx agno connect ``` It auto-detects Claude Code, Claude Desktop, Codex, and Cursor and registers `http://localhost:8000/mcp` . After a successful connection, open one of these apps and ask: ``` can you access my agentos mcp? ``` **claude.ai and ChatGPT (web).** Hosted AI apps reach your platform over the internet and need an OAuth login. Deploy to production (above), add `https:///mcp` as a remote connector, and approve the consent page with your connect secret. | Variable | Required | Default | Description | |---|---|---|---| `OPENAI_API_KEY` | yes | none | OpenAI key for models and embeddings. | `RUNTIME_ENV` | no | `prd` | `dev` disables JWT. Compose sets this to `dev` for local — never put it in an env file that syncs to Railway, or production deploys unauthenticated. | `JWT_VERIFICATION_KEY` | prd | none | Public key from os.agno.com. Required when `RUNTIME_ENV=prd` , unless `JWT_JWKS_FILE` is set. | `JWT_JWKS_FILE` | prd | none | Path to a JWKS file; alternative to `JWT_VERIFICATION_KEY` for production JWT verification. | `AGENTOS_URL` | no | `http://127.0.0.1:8000` | Scheduler base URL. `scripts/railway/up.sh` auto-sets it to your Railway domain; set by hand only for a custom domain or tunnel. Also the public origin OAuth metadata derives from when `MCP_CONNECT_SECRET` is set. | `MCP_CONNECT_SECRET` | no | none | If set (≥16 chars, e.g. `openssl rand -base64 32` ), `/mcp` becomes its own OAuth 2.1 authorization server so claude.ai and ChatGPT (web) can connect; connecting asks for this secret on a consent page. Requires `AGENTOS_URL` . `scripts/railway/up.sh` auto-generates it on deploy. PAT and JWT bearers keep working alongside. | `AGENTOS_MCP_SIGNING_KEY` | no | none | Optional high-entropy signing-key material (≥32 chars) for OAuth tokens. Unset, a strong key is generated and persisted in the database. Rotating it invalidates outstanding tokens. | `ENABLE_DEPLOY_CHECK` | no | `True` | The reference deployment-check cron runs daily by default. Set `False` to disable; the workflow is runnable on demand regardless. | `ENABLE_SCHEDULED_EVALS` | no | `False` | If `True` , schedules the run-evals workflow daily. Off by default because it uses model calls. | `EVALS_TAG` | no | `smoke` | Eval tag run by the run-evals workflow. | `EVALS_CASE_TIMEOUT_SECONDS` | no | `90` | Default per-case timeout for run-evals runs; applies only to cases that don't set their own `timeout_seconds` . | `EVALS_SUITE_TIMEOUT_SECONDS` | no | `900` | Whole-suite timeout for run-evals runs; per-case timeouts are the granular limit. The default bounds the `smoke` tag's worst case (incl. builder-case teardown). | `PARALLEL_API_KEY` | no | none | Authenticates the WebSearch Agent's Parallel SDK / MCP connection. | `SLACK_BOT_TOKEN` / `SLACK_SIGNING_SECRET` | no | none | Both must be set to enable the Slack interface. | `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASS` / `DB_DATABASE` | no | matches compose | Postgres connection. | `DB_DRIVER` | no | `postgresql+psycopg` | SQLAlchemy driver. | `AGNO_DEBUG` | no | `False` | If `True` , Agno emits verbose debug logs. Compose sets this for dev. | `WAIT_FOR_DB` | no | `False` | If `True` , the entrypoint blocks on the DB before starting. Compose sets this. | [Agno documentation](https://docs.agno.com?utm_source=github&utm_medium=example-repo&utm_campaign=agentos-railway&utm_content=agentos-railway&utm_term=railway)[AgentOS introduction](https://docs.agno.com/agent-os/introduction?utm_source=github&utm_medium=example-repo&utm_campaign=agentos-railway&utm_content=agentos-railway&utm_term=railway)[Agno on GitHub](https://github.com/agno-agi/agno). Drop a star if this is useful.