AgentOS on Google Cloud Run

The agentos-gcp template is for teams that develop locally with Docker and deploy to production on Google Cloud Run.

It includes:

Agno, the team that coordinates platform work, also exposed as the agno MCP 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.

Everything runs in your own Google Cloud project: Cloud Run serves the platform and Cloud SQL holds your data.

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-gcp 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-gcp.git agentos
cd agentos

cp example.env .env

Edit .env and set OPENAI_API_KEY.

Start the platform

docker compose up -d --build

The first build takes a few minutes. Confirm the API is available at localhost:8000/docs.

Verify end to end

./scripts/mcp_check.sh

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

At this point, your AgentOS is running locally.

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://<cloud-run-url>/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`.

First production deployment is blocked in the reviewed template revision. The first gcloud run deploy omits JWT verification configuration, while the app requires it at startup. The script reaches its key prompt only after that deployment succeeds. Setting the key in .env.production alone does not fix this ordering. Verify that the template has corrected this before using up.sh for a new production service. Local Docker setup and management of an already configured service are separate paths.

Prerequisites: gcloud CLI installed and authenticated (gcloud auth login), a project selected (gcloud config set project <id>) with billing enabled, Docker running, and OpenSSL available. The image is built locally and pushed.

Create a production env

cp .env .env.production

Edit .env.production with production values: a different OpenAI key, production-only credentials, a different Slack workspace.

Deploy

The following script is the template’s intended provisioning entry point. For a first production deployment, resolve the limitation above before running it.

./scripts/gcp/up.sh

Enables the required APIs, creates an Artifact Registry repo and pushes a locally-built image to it, provisions Cloud SQL Postgres on a private IP, stores your keys in Secret Manager, and deploys the agent-os Cloud Run service. The first run takes 15-20 minutes: the one-time VPC peering is about 5 minutes and the Cloud SQL instance another 5-10. Once the service URL exists, the script sets AGENTOS_URL to it in a second revision so scheduled jobs reach the platform, and generates MCP_CONNECT_SECRET, the OAuth consent secret for chat apps, into .env.production.

Always-on Cloud Run at this template's sizing (2 vCPU / 4 GiB, min 1 instance, no CPU throttling) is ≈$110/mo list price. The budget knob is 1 vCPU / 2 GiB at ≈$58/mo: edit the --cpu/--memory flags in scripts/gcp/up.sh. Cloud SQL db-g1-small adds ≈$25-35/mo.

Mint your JWT key

The intended post-deploy flow prompts for a JWT_VERIFICATION_KEY; the reviewed revision cannot reach that prompt on a fresh production deployment. Token-Based Authorization is on by default. Production startup requires that verification key or a readable JWKS file at the container path in JWT_JWKS_FILE; otherwise the process exits. The verification configuration must be delivered before an authenticated revision can start.

Open os.agno.com, click Connect OS → Live, and enter your Cloud Run URL.
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.sh prompt. The script saves it to your env file and pushes it to the service through Secret Manager.

If you skip the prompt, add JWT_VERIFICATION_KEY to .env.production later and run ./scripts/gcp/env-sync.sh. For JWKS, add the file to the image build context and run ./scripts/gcp/redeploy.sh, or configure a mount. Then set JWT_JWKS_FILE to its container path in .env.production and run ./scripts/gcp/env-sync.sh. The scripts do not upload or mount the file.

Live AgentOS connections are a paid feature. Use code 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://<cloud-run-url>

For claude.ai and ChatGPT on the web: add https://<cloud-run-url>/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).

Confirm it's live

gcloud run services logs read agent-os --region us-central1 --limit 100

Open https://<cloud-run-url>/docs to confirm the API is serving.

After resolving the first-deploy limitation, confirm the revision is ready and the protected API authenticates requests before treating the deployment as live.

For an existing deployment outside us-central1, export GCP_REGION in your shell before running redeploy or env-sync, and pass that region to gcloud log commands.

Redeploy after code changes

./scripts/gcp/redeploy.sh

Sync environment variables

./scripts/gcp/env-sync.sh

Tear down

./scripts/gcp/down.sh

Deletes the Cloud Run service, the Cloud SQL instance including all data, the Artifact Registry repo, and the Secret Manager secrets created by up.sh and env-sync.sh. The one-time VPC peering stays: it is shared per-VPC infrastructure and costs nothing while unused.