> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agno.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Render Reference
> Commands, customization, environment variables, and troubleshooting for the Render template.
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) |
### 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. Without a `JWT_VERIFICATION_KEY` or `JWT_JWKS_FILE`, the app refuses to serve traffic in production. The platform's job is to keep your data private, so the safe default is refuse to start.
Token-Based Auth gives you three things:
1. **No public access.** The server rejects requests without a valid token.
2. **Per-request identity.** Middleware parses the token and extracts the `user_id`, `session_id`, and custom claims. Each request is tied to a user and session, giving you auditability and traceability.
3. **Granular permissions.** User tokens can run an agent and view their own sessions. Admin tokens read everyone's sessions and test any agent.
To opt out (not recommended), set `authorization=False` in `app/main.py` and push. Use this only inside a private VPC behind another auth layer. Without it, anyone who guesses your onrender.com URL can access your platform.
## Customize
Ask your coding agent to run `/create-new-agent`, or do it by hand. Create `agents/my_agent.py`:
```python theme={null}
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,
)
```
Register it in `app/main.py`:
```python theme={null}
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.
`app/settings.py` defines `default_model()`, used by every agent. Change it in one place:
```python theme={null}
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:
```bash theme={null}
./scripts/generate_requirements.sh
```
Rebuild locally with `docker compose up -d --build`. For production, sync the env and push:
```bash theme={null}
./scripts/render/env-sync.sh
git push
```
Agno ships 100+ toolkits. See [Toolkits](/tools/toolkits/overview).
```python theme={null}
from agno.tools.slack import SlackTools
my_agent = Agent(
...
tools=[SlackTools()],
)
```
1. Edit `pyproject.toml`.
2. Regenerate pins: `./scripts/generate_requirements.sh` (add `upgrade` to refresh every pin).
3. Rebuild locally with `docker compose up -d --build`, or commit and push to redeploy.
Set both variables in your env file:
```bash theme={null}
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](/deploy/interfaces/slack/overview).
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:
```bash theme={null}
./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` disables JWT. Compose sets it for local. Never put it in an env file that syncs to Render, or production deploys unauthenticated. |
| `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 to a JWKS file. Alternative to `JWT_VERIFICATION_KEY`. |
| `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. Also the public origin OAuth metadata derives from when `MCP_CONNECT_SECRET` is set. |
| `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
Expected before the first Blueprint launch. Open [dashboard.render.com](https://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.
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.
Expected. Mint the key at [os.agno.com](https://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 do it later, skip the prompt, add `JWT_VERIFICATION_KEY` or `JWT_JWKS_FILE` to `.env.production`, and run `./scripts/render/env-sync.sh`.
JWT auth is on whenever `RUNTIME_ENV` is not `dev`. Set `JWT_VERIFICATION_KEY` or `JWT_JWKS_FILE` and sync. To opt out inside a private VPC behind another auth layer, set `authorization=False` in `app/main.py`.
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.
`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`.
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.