Kubernetes
AgentOS on Kubernetes
AgentOS template for teams that develop locally with Docker and deploy to production on Kubernetes with Helm.
The agentos-helm template is for teams that develop locally with Docker and deploy to production on Kubernetes with Helm.
It includes:
- Agno, the team that coordinates platform work, also exposed as the
agnoMCP tool. - Platform Builder, which creates and updates agents, teams, and workflows through the runtime.
- Platform Manager, which inspects the platform, eval history, deployment checks, and schedules.
- Platform Engineer, which inspects the project’s source code.
- Eight skills for setting up, building, testing, reviewing, and deploying the project with a coding agent.
Coding agents can use these skills with the AgentOS API, evals, traces, and container logs to inspect and improve the platform.
The Helm chart in charts/agentos deploys to any Kubernetes cluster, cloud-managed (EKS, GKE, AKS) or your own.
Get started
Copy the prompt below into Claude Code, Cursor, or Codex to configure and run the template with a 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 in, and run the setup-platform skill (in .agents/skills/).Prefer to drive yourself? Follow the manual steps below.
Manual setup
Prerequisites: Docker installed and running. An OpenAI API key.
Clone and configure
git clone https://github.com/agno-agi/agentos-helm.git agentos
cd agentos
cp example.env .envEdit .env and set OPENAI_API_KEY.
Start the platform
docker compose up -d --buildThe first build takes a few minutes. Confirm the API is available at localhost:8000/docs.
Verify end to end
./scripts/mcp_check.shPrints MCP OK with the tool count and a real agent answer through the MCP endpoint.
Connect the AgentOS UI
- Open os.agno.com and sign in.
- Click Connect OS, enter
http://localhost:8000, and name it Local AgentOS.
Build your first agent
- Chat with Platform Builder: "Build an agent that tracks AI news and writes a daily brief". Go through the agent development process.
- Once created, click Refresh on the top right, pick the new agent from the Agents dropdown, and ask: "What's new with Anthropic?"
- Ask Platform Manager: "How healthy is the platform?" It answers from eval history, deployment checks, schedules, and the agent you just built.
Connect your frontends
| Frontend | How |
|---|---|
| MCP clients on your machine | uvx agno connect auto-detects Claude Code, Claude Desktop, Codex, and Cursor and registers http://localhost:8000/mcp. Verify from the app: "can you access my agentos mcp?" |
| AgentOS UI | os.agno.com → Connect OS → http://localhost:8000. |
| claude.ai and ChatGPT | Hosted sessions can't reach localhost. Deploy to production first, then add https://<your-agentos-domain>/mcp as a custom connector and approve the consent page with the MCP_CONNECT_SECRET that up.sh generates. |
| Slack | Set SLACK_BOT_TOKEN and SLACK_SIGNING_SECRET. See Slack setup. |
| Your product | Call the AgentOS REST API with 80+ endpoints. Browse them at /docs. |
Deploy to production
Prerequisites: kubectl pointed at your cluster, Helm 3+, a container registry the cluster can pull from, and OpenSSL.
Create a production env
cp .env .env.productionEdit .env.production with production values: a different OpenAI key, production-only credentials, a different Slack workspace.
Pick your image
The chart defaults to the official agnohq/agentos image, with the chart defaulting to the moving latest tag. To deploy the source you have inspected, or any customization such as a new agent, build and push your own image with an immutable tag:
docker build -t <registry>/agentos:v1 .
docker push <registry>/agentos:v1Testing on a local kind cluster instead? Run docker build -t agentos:kind . && kind load docker-image agentos:kind, then deploy with IMAGE_REPOSITORY=agentos IMAGE_TAG=kind IMAGE_PULL_POLICY=Never ./scripts/k8s/up.sh. The README's "Local dry run on kind" section has the full flow.
Deploy
./scripts/k8s/up.sh # official image
IMAGE_REPOSITORY=<registry>/agentos IMAGE_TAG=v1 ./scripts/k8s/up.sh # your own buildHelm-installs the chart into the agentos namespace of your current kubectl context (the script shows the context and asks first): the API deployment at the template’s default of one replica, plus in-cluster Postgres with pgvector and its volume. The script also generates a DB_PASS and saves it to your env file. Keep it; the Postgres volume reads the password only on first initialization.
To publish behind your ingress controller, point the hostname’s DNS to the controller and add INGRESS_HOST=os.example.com (and optionally INGRESS_CLASS=nginx). These variables configure routing only. Before deploying, configure trusted HTTPS at your ingress controller or external proxy. For controller-managed TLS, create a TLS Secret in the agentos namespace and set the matching host and Secret in charts/agentos/values.yaml:
ingress:
tls:
- hosts:
- os.example.com
secretName: agentos-tlsThe Secret must already contain a certificate and key for that hostname. See Kubernetes Ingress TLS. AGENTOS_URL then points at that host; otherwise the scheduler uses the in-cluster service DNS, which works out of the box. When the deploy has a public URL (INGRESS_HOST or an explicit AGENTOS_URL), the script also generates MCP_CONNECT_SECRET, the OAuth consent secret for connecting chat apps, and saves it to your env file.
Bringing your own Postgres instead? It must have the pgvector extension available. Install with postgres.enabled=false and the externalDatabase.* values in charts/agentos/values.yaml.
Mint your JWT key
The script pauses for a JWT_VERIFICATION_KEY. Token-Based Authorization is on by default. Production startup requires that verification key or a readable JWKS file at the pod path in JWT_JWKS_FILE; otherwise the process exits.
- Open os.agno.com, click Connect OS → Live, and enter your AgentOS URL (your ingress host, or a tunnel while testing).
- Name it Live AgentOS, turn on Token-Based Authorization (JWT) on the connection panel, and connect. The UI generates the public key. If the OS is already connected, enable the setting under Settings → OS & Security.
- Copy the public key and paste the full PEM into the
up.shprompt. The script saves it to your env file and deploys.
If you skip the prompt, add JWT_VERIFICATION_KEY to .env.production later and run ./scripts/k8s/env-sync.sh. For JWKS, provide the file through a custom image or chart volume, set JWT_JWKS_FILE to its pod path, then deploy. The current chart only forwards the path.
PLATFORM30 for one month off.Connect your MCP clients
Re-run uvx agno connect, this time pointed at your deployed domain:
uvx agno connect --url https://<your-agentos-domain>For claude.ai and ChatGPT on the web: add https://<your-agentos-domain>/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; deployed without INGRESS_HOST? set MCP_CONNECT_SECRET and a public AGENTOS_URL in .env.production and run ./scripts/k8s/env-sync.sh).
Confirm it's live
kubectl rollout status deployment/agentos -n agentos
kubectl logs deploy/agentos -n agentos -fWith an ingress, open https://<your-agentos-domain>/docs to confirm the API is serving. No ingress yet? Port-forward and open localhost:8000/docs:
kubectl port-forward svc/agentos 8000:8000 -n agentosRedeploy after code changes
Build and push a new tag, then roll the release to it:
docker build -t <registry>/agentos:v2 . && docker push <registry>/agentos:v2
IMAGE_TAG=v2 ./scripts/k8s/redeploy.shImmutable tags keep rollbacks one helm rollback away. Running ./scripts/k8s/redeploy.sh without IMAGE_TAG restarts the pods in place; that only picks up a re-pushed tag if the new image actually reached the cluster.
Sync environment variables
./scripts/k8s/env-sync.shChanged supported values roll the pod automatically. env-sync.sh updates RUNTIME_ENV, AGENTOS_URL, OPENAI_API_KEY, JWT_VERIFICATION_KEY, MCP_CONNECT_SECRET, AGENTOS_MCP_SIGNING_KEY, PARALLEL_API_KEY, SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET, and DB_PASS. It updates the JWT_JWKS_FILE path only. The current chart does not upload or mount the referenced file. Use JWT_VERIFICATION_KEY, a custom image containing the file, or a chart extension with a Secret volume. Set ENABLE_DEPLOY_CHECK and EVALS_* via extraEnv and helm upgrade. Enable the registered run-evals schedule from the AgentOS UI.
Tear down
./scripts/k8s/down.shUninstalls the release and deletes the Postgres volume, including all data. The namespace stays in place since it may be shared; the script prints the command to delete it too.