Skip to content
Public template

About

AgentOS: Serve agents over API, MCP, and chat interfaces like Slack

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

AgentOS: The self-driving agent platform

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 Kubernetes (Helm).

Use your agents in:

  1. Your product: call them through the REST API.
  2. Claude and ChatGPT: connect through the MCP server.
  3. 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-helm 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.

1. Start the platform

git clone https://github.com/agno-agi/agentos-helm 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

  1. Open os.agno.com and sign in.
  2. Choose Connect OS, select a local connection, and enter http://localhost:8000.
  3. 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:

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
Harden an agent with simulations and targeted fixes /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.

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 in production

Ask your coding agent to follow deploy-platform, or use the steps below.

You'll need kubectl pointed at the intended cluster, Helm 3 or newer, Docker, a container registry your cluster can pull from, and OpenSSL.

1. Set your production settings

[ -f .env.production ] || cp example.env .env.production

Add 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 and pass every model key to the chart as a Secret.

Build and push this checkout to your registry so the deployment uses this version. Do not assume the chart's default latest image contains these changes.

2. Deploy and set up authentication

Installs charts/agentos in your current Kubernetes context. The script shows the context before proceeding. Configure an ingress controller and HTTPS for your public hostname.

docker build -t YOUR_REGISTRY/agentos:agno-3.1.12 .
docker push YOUR_REGISTRY/agentos:agno-3.1.12

Set IMAGE_REPOSITORY, IMAGE_TAG, and INGRESS_HOST in .env.production before deployment.

./scripts/k8s/up.sh

This creates or uses billed resources. Start with one API instance; see the scaling guide for the optional multi-replica architecture. When the script shows the public URL and asks for a verification key:

  1. Open os.agno.com, choose Connect OS, and select Live.
  2. Enter the public URL and enable token-based authorization.
  3. 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/k8s/env-sync.sh to finish. Production requires a valid token to access agents and data.

3. Check the deployment

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:

kubectl -n agentos logs -f deployment/agentos

Connect your AI apps

Use 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-DOMAIN

Try asking OS Manager about the platform to check that the connection works.

Update or remove the deployment

What you want to do Command
Deploy code changes ./scripts/k8s/redeploy.sh
Upload production settings ./scripts/k8s/env-sync.sh
Remove the deployment ./scripts/k8s/down.sh

Uninstalls the Helm release. Check retained persistent volumes separately before deleting any database storage. Review the resources listed before confirming deletion.

For code changes, build and push a new tag to the same image repository, then run IMAGE_TAG=YOUR_NEW_TAG ./scripts/k8s/redeploy.sh. This keeps the repository from the original deployment. Environment sync reads the production env file.

Sandbox storage

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.

Upgrading legacy checkpoint storage

If an older release enabled checkpoints.enabled, keep its existing checkpoint values on the first upgrade (the redeploy and env-sync scripts use --reuse-values). The chart retains that claim and marks it helm.sh/resource-policy: keep; the new API does not mount it. Back up its files before migrating to S3. Existing local checkpoints are not automatically copied or restored from S3.

After verifying the backup and the new sandbox setup, you can disable the legacy checkpoint setting. The claim remains for deliberate cleanup and may continue to incur storage charges. A claim supplied through checkpoints.existingClaim remains operator-owned. New installations leave legacy storage disabled.

Coding agent backend

The chart selects sandboxProvider: agentcore. Put ARN, checkpoint bucket/prefix and AWS_REGION in extraEnv values. For AWS keys, GH_TOKEN, and an optional GITHUB_READ_TOKEN, use extraEnv entries with valueFrom.secretKeyRef pointing to a separately managed Kubernetes Secret; never commit token values in a values file. The scripts/k8s/ env-file parser does not forward these optional keys. Apply your private values file with helm upgrade for the existing release, alongside the current values. Use workload identity for scoped AWS access when available.

Enable coding agents and SANDBOX_ENABLED in code only after completing the harness setup; retain production JWT settings.

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 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.

Learn more

About

AgentOS: Serve agents over API, MCP, and chat interfaces like Slack

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages