# Render Reference (/deploy/templates/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 [#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 [#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 [#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:
1. **Protected AgentOS routes require a token.** The operational and docs routes `/`, `/health`, `/info`, `/docs`, `/redoc`, `/openapi.json`, and `/docs/oauth2-redirect` remain public.
2. **Per-request identity.** Middleware validates the token and exposes its `user_id`, optional `session_id`, scopes, and claims to the request.
3. **Scope-based permissions.** Token scopes control access to AgentOS routes and resources.
The template already sets `AuthorizationConfig(user_isolation=True)`. Authenticated non-admin REST access is scoped to the principal; local `dev` mode disables scope enforcement and is open when no credentials are configured. This does not scope Platform Manager’s direct database tools to that REST identity. See [User Isolation](/agent-os/security/authorization/user-isolation) for the boundaries and admin exceptions.
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 [#customize]
Ask your coding agent to run `/create-agent`, or do it by hand. Create `agents/my_agent.py`:
```python
from agno.agent import Agent
from app.learning import shared_learning
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",
user_id="anonymous-user", # Local fallback; authenticated runs supply identity.
model=default_model(),
db=get_postgres_db(),
instructions=INSTRUCTIONS,
learning=shared_learning,
add_datetime_to_context=True,
add_history_to_context=True,
num_history_runs=5,
)
```
The fallback user ID lets local anonymous calls use the shared learning machine; those calls share one profile. Authenticated run identity overrides this default.
Import it in `app/main.py` and update the `agents` argument in the existing `AgentOS` call. Keep its other arguments, including teams, workflows, knowledge, and registry:
```python
from agents.my_agent import my_agent
agent_os = AgentOS(
# Keep the other arguments from the existing call.
agents=[platform_builder, platform_manager, platform_engineer, my_agent],
)
```
Add its UI metadata beneath the existing `manifest:` key in `app/config.yaml`:
```yaml
my-agent:
description: "What the agent does."
quick_prompts:
- "First example prompt"
- "Second example prompt"
- "Third example prompt"
```
Local containers reload Python source changes. After editing `app/config.yaml`, run `docker compose restart agentos-api` to reload the manifest. For production, commit and push; Render rebuilds automatically.
`app/settings.py` defines `default_model()`, used by every agent. Change it in one place:
```python
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
./scripts/generate_requirements.sh
```
Rebuild locally with `docker compose up -d --build`. For production, commit the Python, `pyproject.toml`, and regenerated requirements changes, then sync the env and push the commit:
```bash
./scripts/render/env-sync.sh
git push
```
Agno ships 100+ toolkits. See [Toolkits](/tools/toolkits/overview).
```python
from agno.tools.slack import SlackTools
my_agent = Agent(
# Keep the agent’s existing configuration.
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
SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...
```
Sync with `./scripts/render/env-sync.sh`. The interface activates automatically and routes messages to the Agno team. Change `team=` in `app/main.py` to select another team, or replace it with `agent=my_agent` to route to an agent. See [Slack setup](/agent-os/interfaces/slack/setup).
The deployment check runs daily by default (`ENABLE_DEPLOY_CHECK=True`); it uses fixed checks without model calls. The `run-evals` schedule is always registered but starts disabled because it uses model calls. Enable it from the AgentOS UI. Both workflows remain runnable on demand. Startup reapplies `ENABLE_DEPLOY_CHECK` to the deployment-check schedule; the enabled state of an existing `run-evals` schedule is preserved.
## Format, validate, and run evals [#format-validate-and-run-evals]
Run evals against a dedicated local test platform with no concurrent writers. The starter’s cleanup hooks remove components and learning state created during a case; concurrent application writes can be removed too. The same prerequisite applies to scheduled evals. See [eval setup and isolation](/deploy/coding-agents#keep-behavior-stable-with-evals).
The host scripts require [uv](https://docs.astral.sh/uv/getting-started/installation/). The setup script creates a Python 3.14 venv:
```bash
./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 [#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` sends the generated onrender.com URL when no value exists locally; use `env-sync.sh` to deliver a preconfigured or custom URL. Loopback reaches the app inside this container; set the public URL for hosted MCP OAuth and the template’s deployment check. 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. |
| `EVALS_TAG` | No | `smoke` | Eval tag the run-evals workflow runs. |
| `EVALS_CASE_TIMEOUT_SECONDS` | No | `90` | Fallback timeout for cases without an explicit timeout. |
| `EVALS_SUITE_TIMEOUT_SECONDS` | No | derived from selected cases | Sum of selected case timeouts plus 30 seconds per case, with a 60-second floor. A positive integer overrides this ceiling. |
| `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 [#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. At [os.agno.com](https://os.agno.com), choose **Connect OS** → **Live**, enter your onrender.com 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**. Paste the full PEM into the script prompt. 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.
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.
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.
Check that the schedule is enabled, the scheduler is running, and its request URL is reachable from the container. Inspect application logs for request or authentication failures. The default loopback URL reaches the app on port 8000. For hosted MCP OAuth, set a public `AGENTOS_URL` 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.