AgentOS is a durable agent runtime that serves agents over API, MCP, and chat interfaces like Slack. Build agents for your product, your team, or yourself. Run them in your own cloud, keep their data in your own database, and manage them from AgentOS.
Built with Agno, this template gives you a working agent platform that you can run locally or deploy to Google Cloud Run.
Three ways to build agents.
- Use a coding agent. Open the repo in Claude Code, Codex, or Cursor. The included skills help it create, test, and improve your agents.
- Describe what you need. Chat with OS Manager, the built-in agent that helps you manage the platform and build new agents.
- Use Studio. Build agents visually in AgentOS Studio.
Three ways to use your agents.
- In your product. Call your agents through the REST API.
- In AI apps. Connect apps such as Claude and ChatGPT through MCP.
- In Slack. Connect a Slack app to talk to OS Manager from your workspace.
The AgentOS UI lets you chat with your agents, review past conversations, and see the steps an agent took. Your PostgreSQL database stores conversations, memories, and Company work.
Copy this prompt into your coding agent:
Help me set up my agent platform and build my first agent.
Clone https://github.com/agno-agi/agentos-gcp 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 follow setup-platform in that folder.
Prefer to set it up yourself? Follow the steps below.
You'll need Git, Docker with Compose, and an OpenAI API key. Make sure Docker is running. Run the commands below in a terminal.
git clone https://github.com/agno-agi/agentos-gcp agent-platform
cd agent-platform
cp example.env .envOpen .env and set OPENAI_API_KEY. Then start the platform:
docker compose up -d --buildThe 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.shThe check should report 9 tools; required tools available.
- 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.
Tell OS Manager what you want to build. For example:
Help me build an agent that answers questions about my product. Here's the documentation URL: …
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.
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:
| What you want to do | Skill |
|---|---|
| Build an agent | /create-agent |
| Add a tool, change behavior, or fix a bug | /extend-agent |
| Write tests for your agent's answers | /create-evals |
| Fix failing tests or try more scenarios | /eval-and-improve |
| Check the repo before sharing or releasing it | /review-and-improve |
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. Keep a product's documentation in its own knowledge base, separate from the platform's documents.
Company organizes ongoing work. A Product is what you're working on, a Project groups related work, and a Task is one piece of work to complete. A Routine is a set of instructions that can run on a schedule.
This template includes an AgentOS Product for improving the platform itself. To get started, ask OS Manager:
Review this codebase and recent Agno releases. Suggest the most useful improvements.
It also includes a daily review at 09:00 UTC. 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. Automatic acceptance is off.
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.
The platform includes Claude Engineer and Codex Engineer. They can read your code, make changes, and run commands.
Chat with either engineer 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.
Codex uses the OPENAI_API_KEY you added during setup. To use Claude, add
ANTHROPIC_API_KEY to .env. After changing .env, run docker compose up -d again.
By default, engineers work in this project's folder. When running locally with Docker Compose, their file changes appear in your local checkout. Review those changes before committing them.
You don't need to configure a sandbox or repository URL to get started.
To have engineers work on a separate copy of your repository, follow the sandbox setup guide for Docker or AWS AgentCore.
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 HEADFuture 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.
Ask your coding agent to follow deploy-platform, or use the steps below. For an existing deployment, read the upgrade guide first.
You'll need Google Cloud CLI with gcloud auth login completed, a project with billing enabled, Docker, and OpenSSL.
[ -f .env.production ] || cp example.env .env.productionAdd OPENAI_API_KEY and any other model keys you use, such as ANTHROPIC_API_KEY
or CLAUDE_CODE_OAUTH_TOKEN for Claude Engineer. Keep RUNTIME_ENV=prd or leave
it unset. The scripts read .env.production before .env; credential-shaped keys
land in Secret Manager, the rest become plain environment variables.
Set GCP_PROJECT_ID in .env.production, or select the project with gcloud config set project YOUR_PROJECT_ID. Keep one service instance; the scheduler runs inside the API.
Creates Artifact Registry, Cloud SQL PostgreSQL and a Cloud Run service. The service keeps a minimum of one instance and CPU available between requests so scheduled jobs can run.
./scripts/gcp/up.shThis creates or uses billed resources. Keep one API instance so scheduled work runs once. When the script shows the public URL and asks for a verification key:
- Open os.agno.com, choose Connect OS, and select Live.
- Enter the public URL and enable token-based authorization.
- Copy the full public verification key into the script's prompt.
The script saves the key and connection settings in .env.production. If you
skipped the prompt, save the quoted JWT_VERIFICATION_KEY there and run
./scripts/gcp/env-sync.sh to finish. Production requires a valid token
to access agents and data.
Open /health and /docs on your public URL, then connect through the AgentOS UI.
Check that /agents rejects requests without a token and works with a valid token.
View logs with:
gcloud run services logs read agent-os --region YOUR_REGIONUse your public URL followed by /mcp as the connector URL in an AI app.
When prompted, enter the MCP_CONNECT_SECRET saved in your production env file.
For a supported coding client, run:
uvx agno connect --url https://YOUR-DOMAINTry asking OS Manager about the platform to check that the connection works.
| What you want to do | Command |
|---|---|
| Deploy code changes | ./scripts/gcp/redeploy.sh |
| Upload production settings | ./scripts/gcp/env-sync.sh |
| Remove the deployment | ./scripts/gcp/down.sh |
Deletes the managed Cloud Run service, database and related resources created by the scripts. Review the resources listed before confirming deletion.
Local Docker sandbox instructions are in the sandbox guide.
The production deployment does not attach sandbox checkpoint storage. Before
enabling AWS AgentCore, add a Cloud Run volume mounted at /data (a Filestore
NFS share, or a Cloud Storage bucket through the Cloud Storage FUSE volume type)
with gcloud run services update --add-volume and --add-volume-mount, and put
the AWS credentials AgentCore needs in .env.production so the sync stores them
as secrets. If you skip the mount, leave AgentCore disabled. Keep one API instance.
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 smokevalidate.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.
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 deployment.
| 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. Deployment scripts save it for you. |
MCP_CONNECT_SECRET |
Connect browser MCP clients. Deployment scripts generate 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. |