Render Reference

The web service is agent-os and the database is agentos-db. Every command in scripts/render/ drives the Render API and needs RENDER_API_KEY in your environment or env file.

Manage

Task	Command
Deploy code changes	Push to your deploy branch. `autoDeploy: true` in `render.yaml` rebuilds automatically.
Re-run a build without a commit	`./scripts/render/redeploy.sh`
Sync env variables	`./scripts/render/env-sync.sh` (defaults to `.env.production`; pass `.env` to sync that instead)
Tail logs	Dashboard: `agent-os` → Logs
Tear down	`./scripts/render/down.sh` (add `--yes` to skip the confirmation)

./scripts/render/down.sh --yes skips confirmation and deletes both the agent-os web service and the agentos-db Postgres database, including all database data.

Auto-deploy on merge

autoDeploy: true is on in render.yaml, so every push to your deploy branch triggers a build and deploy. Render builds the pushed branch; local uncommitted changes never deploy. ./scripts/render/env-sync.sh is still how you sync env changes.

Production auth

Token-Based Authorization is on by default. Production startup requires JWT_VERIFICATION_KEY or a readable JWKS file at the container path in JWT_JWKS_FILE; otherwise the process exits. Token-Based Auth gives you three things:

Protected AgentOS routes require a token. The operational and docs routes /, /health, /info, /docs, /redoc, /openapi.json, and /docs/oauth2-redirect remain public.
Per-request identity. Middleware validates the token and exposes its user_id, optional session_id, scopes, and claims to the request.
Scope-based permissions. Token scopes control access to AgentOS routes and resources.

The templates do not enable per-user data isolation. To scope non-admin session, memory, trace, and run access to the JWT subject, pass authorization_config=AuthorizationConfig(user_isolation=True) to AgentOS. See User Isolation. To disable JWT authentication, set authorization=False in app/main.py, remove JWT_VERIFICATION_KEY and JWT_JWKS_FILE from the Render service, and push. Use this only inside a private VPC behind another auth layer. authorization=False disables AgentOS scope enforcement, while configured JWT environment variables still enable JWT validation. MCP OAuth remains active when MCP_CONNECT_SECRET is set.

Customize

Add an agent

Ask your coding agent to run /create-new-agent, or do it by hand. Create agents/my_agent.py:

from agno.agent import Agent

from app.settings import default_model
from db import get_postgres_db

INSTRUCTIONS = """\
What the agent does, which tools it uses, the rules to follow when answering.
"""

my_agent = Agent(
    id="my-agent",
    name="My Agent",
    model=default_model(),
    db=get_postgres_db(),
    instructions=INSTRUCTIONS,
    enable_agentic_memory=True,
    add_datetime_to_context=True,
    add_history_to_context=True,
    num_history_runs=5,
)

from agents.my_agent import my_agent

agent_os = AgentOS(
    ...
    agents=[agent_builder, platform_manager, web_search, my_agent],
)

Local containers hot-reload on save. For production, commit and push; Render rebuilds automatically.

Change the model

app/settings.py defines default_model(), used by every agent. Change it in one place:

from agno.models.anthropic import Claude

def default_model():
    return Claude(id="claude-sonnet-5")

Add anthropic to pyproject.toml, set the provider key in your env, and regenerate pins:

./scripts/generate_requirements.sh

Rebuild locally with docker compose up -d --build. For production, sync the env and push:

./scripts/render/env-sync.sh
git push

Add tools

Agno ships 100+ toolkits. See Toolkits.

from agno.tools.slack import SlackTools

my_agent = Agent(
    ...
    tools=[SlackTools()],
)

Add dependencies

Edit pyproject.toml.
Regenerate pins: ./scripts/generate_requirements.sh (add upgrade to refresh every pin).
Rebuild locally with docker compose up -d --build, or commit and push to redeploy.

Enable Slack

Set both variables in your env file:

SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...

Sync with ./scripts/render/env-sync.sh. The interface activates automatically and routes messages to Agent Builder; change the agent= argument in app/main.py to point at another agent. See Slack setup.

Toggle scheduled workflows

The deployment check runs daily by default (ENABLE_DEPLOY_CHECK=True); it is deterministic and free. Scheduled evals are off by default (ENABLE_SCHEDULED_EVALS=False) because they use model calls. Both workflows stay runnable on demand regardless.

Format, validate, and run evals

The format, validate, and eval scripts run on the host and need a venv. Set it up once:

./scripts/venv_setup.sh
source .venv/bin/activate

Task	Command
Format	`./scripts/format.sh`
Lint and type-check	`./scripts/validate.sh`
Run smoke evals	`python -m evals --tag smoke`

./scripts/mcp_check.sh runs inside the container, so it needs no venv.

Environment variables

Variable	Required	Default	Description
`OPENAI_API_KEY`	Yes	-	Models and embeddings. The Blueprint prompts for it at launch.
`RENDER_API_KEY`	Deploy scripts	-	Drives the Render API in `scripts/render/`. The scripts read it from your environment or env file; `env-sync.sh` never pushes `RENDER_*` keys to the service.
`RUNTIME_ENV`	No	`prd`	`dev` sets `authorization=False`, which disables AgentOS scope enforcement. Configured JWT environment variables still enable JWT validation. Compose sets `dev` locally; keep `prd` on Render.
`JWT_VERIFICATION_KEY`	Production	-	Public key from os.agno.com. Quote the value so the multi-line PEM parses as one variable.
`JWT_JWKS_FILE`	Production	-	Path inside the running container to a JWKS JSON file. The scripts set only this path. Commit and push the file into the image build context and let auto-deploy rebuild the service, or configure a platform mount and roll the service.
`MCP_CONNECT_SECRET`	No	generated by `up.sh`	OAuth consent secret (16+ chars) for connecting claude.ai and ChatGPT to `/mcp`. `up.sh` generates one on deploy and writes it to `.env.production`.
`AGENTOS_MCP_SIGNING_KEY`	No	generated	Optional high-entropy signing-key material (32+ chars) for OAuth tokens. Unset, a strong key is generated and persisted in the database. Rotating it invalidates outstanding tokens.
`AGENTOS_URL`	No	`http://127.0.0.1:8000`	Scheduler base URL. `up.sh` pins it to your onrender.com URL. Scheduled jobs never fire if it stays at the default in production. When `MCP_CONNECT_SECRET` is set, OAuth metadata also derives its public origin from this URL.
`ENABLE_DEPLOY_CHECK`	No	`True`	Daily deployment-check cron.
`ENABLE_SCHEDULED_EVALS`	No	`False`	Daily run-evals cron. Uses model calls.
`EVALS_TAG`	No	`smoke`	Eval tag the run-evals workflow runs.
`EVALS_CASE_TIMEOUT_SECONDS`	No	`90`	Per-case timeout for run-evals runs.
`EVALS_SUITE_TIMEOUT_SECONDS`	No	`900`	Whole-suite timeout for run-evals runs.
`PARALLEL_API_KEY`	No	-	WebSearch uses the Parallel SDK when set, keyless MCP otherwise.
`SLACK_BOT_TOKEN`	No	-	Set with the signing secret to enable Slack.
`SLACK_SIGNING_SECRET`	No	-	Set with the bot token to enable Slack.
`DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASS` / `DB_DATABASE`	No	matches compose	Postgres connection. The Blueprint wires them from `agentos-db`.
`DB_DRIVER`	No	`postgresql+psycopg`	SQLAlchemy driver.
`AGNO_DEBUG`	No	`False`	Verbose Agno logs. Compose sets it for dev.
`WAIT_FOR_DB`	No	`False`	If `True`, the entrypoint blocks on the database before starting. Compose and the Blueprint set it.

Troubleshooting

up.sh reports no agent-os service

Expected before the first Blueprint launch. Open dashboard.render.com → New + → Blueprint, connect your copy of the repo, and apply. The script prints these steps and polls every 15 seconds for up to 30 minutes, so you can leave it running while you launch.

RENDER_API_KEY not set

Create one in the dashboard under Account Settings → API Keys, then export it or add it to .env.production. The scripts read it from either place.

up.sh pauses asking for a JWT key

Expected. Mint the key at os.agno.com: connect your OS (Connect OS → Live, enter your onrender.com URL), then turn on Token-Based Authorization (JWT) under Settings → OS & Security and paste the full PEM. To add a PEM later, set JWT_VERIFICATION_KEY and run ./scripts/render/env-sync.sh. To use JWKS, commit and push the file into the image build context, or configure a mount. Set JWT_JWKS_FILE to its container path, then let auto-deploy rebuild or roll the service. Env sync alone only updates the path.

App fails to start in production

JWT scope enforcement is on whenever RUNTIME_ENV is not dev. Set JWT_VERIFICATION_KEY and sync. For JWKS, verify the file exists inside the container at JWT_JWKS_FILE; changing the variable alone does not deliver it. To disable JWT inside a private VPC behind another auth layer, set authorization=False in app/main.py and remove both JWT environment variables from the Render service. MCP OAuth remains active when MCP_CONNECT_SECRET is set.

My code changes didn't deploy

Render builds the pushed branch, so local uncommitted changes stay on your machine. Commit, push to your deploy branch, and let autoDeploy rebuild. redeploy.sh warns when it finds uncommitted changes.

Scheduled jobs never fire

AGENTOS_URL is still the localhost default. up.sh pins it to your onrender.com URL automatically, and env-sync.sh pins it when your env file has none; for a custom domain or tunnel, set it by hand and run ./scripts/render/env-sync.sh.

Scheduler or MCP streams stop working

The service is likely on the free plan, which sleeps between requests; the in-process scheduler and MCP streams stop when it does. Set plan: starter (or higher) in render.yaml and push.

Get Started

Starters

Apps

Agno CLI

Render Reference

Manage

Auto-deploy on merge

Production auth

Customize

Format, validate, and run evals

Environment variables

Troubleshooting

​Manage

​Auto-deploy on merge

​Production auth

​Customize

​Format, validate, and run evals

​Environment variables

​Troubleshooting

Manage

Auto-deploy on merge

Production auth

Customize

Format, validate, and run evals

Environment variables

Troubleshooting