Build agents for your company, product, or customers. Run them as durable
services on AgentOS. Put them to work automating company operations.
- Build agents with the Agno, Claude Agent, or Codex SDKs. Combine agents into
teams and workflows.
- Run agents as durable services with built-in API and MCP. AgentOS handles
authentication, role-based access, human approvals, scheduling, and durable execution.
- Automate company operations with CompanyOS. Give agents responsibilities,
organize work into projects and tasks, and configure recurring routines. People set
direction and review results; agents own and execute.
Built with Agno, this template gives you a working
agent platform that you can run locally or deploy to Railway.
Use your agents in:
- Your product: call them through the REST API.
- Claude and ChatGPT: connect through the MCP server.
- Slack: connect a Slack app to talk to OS Manager from your workspace.
Run your platform in your own cloud and keep your data in your own PostgreSQL database.
Use the AgentOS UI to review conversations, inspect traces,
manage knowledge, and track your agents’ work. Build agents with code, use Studio,
or chat with OS Manager.
Get started
Give this prompt to your coding agent:
Help me set up my agent platform and build my first agent.
Clone https://github.com/agno-agi/agentos-railway into a folder called agent-platform,
cd into it, and follow .agents/skills/setup-platform/SKILL.md.
It checks Docker, helps you add your API key, starts the platform, and walks you
through building your first agent. Already cloned the repo? Ask your coding agent
to run the /setup-platform skill.
Coding agents
The platform includes Claude Engineer and Codex Engineer, disabled by default.
They can read code, make changes, and run commands. Enable them in app/main.py.
Follow the harness setup guide for the steps.
Once enabled, chat with a coding agent in AgentOS or ask OS Manager to use one:
Ask Codex Engineer to review this project and suggest improvements. Don’t change any files yet.
Without a sandbox, coding agents run on the API host with its file and credential
access. For isolation and checkpoint recovery, set up a
Docker or AgentCore sandbox.
Run locally
You’ll need Git, Docker with Compose, and an OpenAI API key.
Make sure Docker is running, then run the commands below in your terminal.
git clone https://github.com/agno-agi/agentos-railway agent-platform
cd agent-platform
cp example.env .env
Open .env and set OPENAI_API_KEY, then start the platform:
docker compose up -d --build
The first build can take a few minutes. When it’s ready, open
http://localhost:8000/docs to see the API.
Check that AI apps can connect through MCP:
./scripts/mcp_check.sh
The check should report 9 tools; required tools available.
2. Connect the UI
- Open os.agno.com and sign in.
- Choose Connect OS, select a local connection, and enter
http://localhost:8000.
- Name it Local AgentOS, then open the chat for OS Manager.
3. Build your first agent
Tell OS Manager what you want to build. For example:
Help me build a daily briefing agent about the companies and topics I follow. Here’s what I care about: …
Review what it proposes, then ask it to build and publish the agent.
Refresh the Agents list and try it out. You can chat with your new agent directly
or ask OS Manager to run it for you.
Build and improve your agents
You can keep working through OS Manager, use Studio, or edit Python files in this repo.
The repo includes instructions, called skills, for common coding tasks.
Ask your coding agent to follow the relevant skill:
If you write an agent in Python, put it in agents/ and add it to
app/main.py so the platform can run it. Set its description and
suggested prompts in app/config.yaml. To make a tool or model
available in Studio, add it to app/registry.py.
You can give agents documents to search, a notebook to keep notes, and memory
to remember each user.
Company
CompanyOS organizes the work you delegate to agents. A Product defines an ongoing
area of responsibility, a Project groups related work toward a goal, and a Task
describes a specific job to complete. Routines give agents instructions to carry
out on a schedule.
This template includes an AgentOS Product for improving the platform itself,
with a daily review routine scheduled for 09:00 UTC. It is disabled by default;
enable it from the Company page in the AgentOS UI. Company Manager reads the
code and Agno release notes, then proposes up to three Tasks for you to review.
The review is instructed to suggest work and leave approval and execution to you.
Scheduled reviews use your model API keys and incur usage costs. Check the saved
schedule and run history in Company to see when a review will run and what it did.
app/company.py sets the initial review instructions and schedule.
Once they’re saved in the database, update the saved Routine to change them;
editing the Python file alone won’t change an existing Routine.
Make it yours
To save your work in your own GitHub repository, create an empty private repo.
From a fresh clone of this template, run the commands below with your repo URL.
This makes origin your repo and keeps the original template as upstream:
git remote rename origin upstream
git remote add origin https://github.com/YOUR-ORG/YOUR-REPO.git
git push -u origin HEAD
Future pushes go to your repository. You can still fetch updates from upstream
and review them before merging.
If you use sandboxes, also set the repository URL and branch in
the sandbox configuration.
Deploy on Railway
Ask your coding agent to follow deploy-platform,
or follow the steps below yourself.
Already deployed? Use the update commands.
1. Prepare your production settings
Install uv and Railway CLI 5.49.0 or newer, then run
railway login. Set up the Python environment used by the deploy scripts
(run deactivate first if another environment is active):
./scripts/venv_setup.sh
[ -f .env.production ] || cp example.env .env.production
Open .env.production and add OPENAI_API_KEY, plus any other API keys you use.
This file holds your Railway settings; .env holds your local settings.
Keep RUNTIME_ENV=prd, or leave it unset.
2. Create the Railway project
Replace YOUR_WORKSPACE with your Railway workspace name or ID:
./scripts/railway/up.sh --workspace YOUR_WORKSPACE
This creates the API service, PostgreSQL database, and public URL. Railway starts
billing for these resources. The script saves the URL and connection settings in
.env.production.
On a first deployment without authentication settings, the script creates the
resources and URL, then stops before starting the API. This is expected
(exit code 2). Continue with step 3 to finish setup; don’t run up.sh again.
3. Set up authentication
- Open os.agno.com, choose Connect OS, and select Live.
- Enter the URL saved as
AGENTOS_URL in .env.production and enable token-based authorization.
- Copy the public verification key into
.env.production as JWT_VERIFICATION_KEY.
Wrap the full key in quotes, including its first and last lines.
- Upload the settings and deploy:
./scripts/railway/env-sync.sh --no-deploy
./scripts/railway/redeploy.sh
Your deployed agents and data require a valid login token. The verification key
lets the server check those tokens.
Check the deployment logs:
railway logs --service agent-os
Confirm that /health responds and that you can connect through the UI. Before sharing,
check that a request to /agents without a token is rejected and one with a valid token works.
4. Connect your AI apps
To connect an AI app that supports MCP, use your Railway URL followed by /mcp
(for example, https://YOUR-DOMAIN/mcp). When the connection page asks for a
secret, enter the MCP_CONNECT_SECRET saved in .env.production.
To connect a supported coding client from your terminal, use your Railway URL:
uvx agno connect --url https://YOUR-DOMAIN
Once connected, the app can talk to OS Manager through the os_manager tool.
Try asking it about your platform to check the connection. Opening /mcp
in a browser is not enough to check that an agent can respond.
Sandbox storage
For AgentCore, add SANDBOX_PROVIDER=agentcore and the settings printed by
scripts/aws.py status to .env.production, then run
./scripts/railway/env-sync.sh. Set the repository and SANDBOX_ENABLED = True
in code only after backend setup; deploy the code with ./scripts/railway/redeploy.sh.
Keep local provisioning profiles in .env; do not upload AWS_PROFILE to Railway.
The API service needs no attached disk. Conversations, memories and Company work
are stored in PostgreSQL. Without a sandbox, engineers run inside the API container;
their edited files and native sessions can be lost on redeploy or replacement.
Database conversation history does not reconstruct that working directory.
For durable, isolated engineering, configure AWS AgentCore and S3.
S3 stores the last saved workspace and native-session checkpoint. Recovery does
not preserve unfinished edits at the instant of a crash or replay external actions
safely. AWS is optional for getting started. Local Docker isolation is also
available in the sandbox guide.
Before running multiple API instances, follow Scaling.
Update or remove the deployment
| What you want to do |
Command |
| Deploy code changes |
./scripts/railway/redeploy.sh |
| Upload settings and redeploy |
./scripts/railway/env-sync.sh |
| Deploy code and settings together |
Run ./scripts/railway/env-sync.sh --no-deploy, then ./scripts/railway/redeploy.sh |
| View logs |
railway logs --service agent-os |
| Delete the project |
./scripts/railway/down.sh |
Deleting the project deletes its database and all its data. Local env files are
kept; review their saved URL and authentication settings before creating a new project.
Removing a line from .env.production does not remove it from Railway. Clear an
optional credential by setting it to an empty value, or remove it in Railway.
Changing the database password needs a separate database update.
Verify and develop
To check your Python code and test agent responses, install uv
and run these commands from the project folder. Keep the local platform running.
If another Python environment is active, run deactivate first.
./scripts/venv_setup.sh
source .venv/bin/activate
./scripts/validate.sh
python -m evals --tag smoke
validate.sh checks Python formatting, lint rules, and types. The smoke tests ask
OS Manager to explain setup, check platform health, and explain agent memory.
They use your model API keys and save results in the database for review in the UI.
PostgreSQL must be running, even when you only want to list the tests.
Add your own cases in evals/cases.py, or use
/create-evals. To save a report, add
--json-output tmp/evals.json. To run one case, use --name CASE_NAME.
Evals use your application’s database and workspace; agents can call tools during a test.
Change dependencies in pyproject.toml, then run ./scripts/generate_requirements.sh.
Commit the updated requirements.txt and rebuild the API and any sandbox image you use.
See AGENTS.md for the code layout and development conventions.
Configuration
example.env shows the main settings. Start with OPENAI_API_KEY;
add the others when you need them. Use .env locally and .env.production for Railway.
| Setting |
What it’s for |
OPENAI_API_KEY |
OS Manager, embeddings, and Codex Engineer. |
ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN |
Claude Engineer. |
SLACK_BOT_TOKEN and SLACK_SIGNING_SECRET |
Connect OS Manager to Slack. Set both. |
PARALLEL_API_KEY |
Optional web search key. Without it, search uses Parallel’s MCP server without an API key. |
JWT_VERIFICATION_KEY or JWT_JWKS_FILE |
Check login tokens in production. A JWKS file must be available on the server. |
AGENTOS_URL |
Public URL used by scheduled jobs and MCP. Railway setup saves it for you. |
MCP_CONNECT_SECRET |
Connect browser MCP clients. Railway setup generates it for you. |
DB_HOST, DB_PORT, DB_USER, DB_PASS, DB_DATABASE |
PostgreSQL connection settings. Local Compose configures these for you. |
RUNTIME_ENV |
prd by default. Local Compose uses dev, which disables token checks. |
Learn more
评论