# Fly.io Reference (/deploy/templates/fly/reference) Fly app names are global, so `up.sh` generates a unique name (`agentos-`), records it in `fly.toml`, and pairs it with a Postgres app named `-db`. Later `fly` commands read the app name from `fly.toml`, so no `--app` flag is needed. ## Manage [#manage] | Task | Command | | ------------------- | --------------------------------------------------------------------------------------------- | | Deploy code changes | `./scripts/fly/redeploy.sh` | | Sync env variables | `./scripts/fly/env-sync.sh` (defaults to `.env.production`; pass `.env` to sync that instead) | | Tail logs | `fly logs` | | Resize the machine | Edit `[[vm]]` in `fly.toml`, then `./scripts/fly/redeploy.sh` | | Tear down | `./scripts/fly/down.sh` (add `--yes` to skip the confirmation) | The platform runs one machine by design. Both deploy scripts pass `fly deploy --ha=false` to keep the template at one machine. Postgres coordinates due-schedule claims across scheduler workers; multiple workers do not inherently run every cron twice. `fly.toml` keeps the machine warm with `auto_stop_machines = "off"` and `min_machines_running = 1`; with scale-to-zero, scheduled jobs silently stop firing. ## 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 runtime access.** Protected API routes require a valid credential. Health, discovery, and API documentation remain public; Slack and MCP OAuth have their own authentication flows. 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 in a private deployment with another auth layer, set `authorization=False`, remove `JWT_VERIFICATION_KEY` and `JWT_JWKS_FILE` from the running service, and rebuild or redeploy the app as needed. Disabling scope enforcement alone does not remove JWT validation while those credentials remain configured. MCP OAuth remains enabled while `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, run `./scripts/fly/redeploy.sh`. `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: ```bash ./scripts/fly/env-sync.sh ./scripts/fly/redeploy.sh ``` 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 redeploy with `./scripts/fly/redeploy.sh`. Set both variables in your env file: ```bash SLACK_BOT_TOKEN=xoxb-... SLACK_SIGNING_SECRET=... ``` Sync with `./scripts/fly/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. Fly's stock `postgres-flex` image does not ship pgvector, so sessions and memory work but knowledge bases (RAG) fail at `CREATE EXTENSION` time. The fix is a two-line Dockerfile: ```dockerfile FROM flyio/postgres-flex:17 RUN apt-get install -y postgresql-17-pgvector ``` Set `FLY_PG_IMAGE` to that image before running `./scripts/fly/up.sh`. The image applies when the Postgres cluster is created; `up.sh` reuses an existing cluster, so switching later means tearing down with `./scripts/fly/down.sh` and provisioning fresh. ## 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. | | `RUNTIME_ENV` | No | `prd` | `dev` disables scope enforcement; configured JWT credentials still enable token validation. Compose sets it for local. Keep production on `prd` so scope enforcement remains enabled. | | `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 Fly Machine to a JWKS file. The Fly scripts sync only this path. Bake the file into the image or configure a Fly mount before deploying. | | `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` sets it to `https://.fly.dev`. Loopback reaches the app inside this container; set the public URL for hosted MCP OAuth and the template’s deployment check. Re-running `up.sh` resets a hand-set value to the generated fly.dev URL, so re-pin the domain (or re-run `env-sync.sh`) afterwards. 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. `up.sh` sets these as Fly secrets pointing at `-db.flycast`. | | `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 sets it. | `up.sh` also reads three variables from your shell when provisioning: | Variable | Default | Description | | -------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------ | | `FLY_REGION` | `iad` | Region for the app and its Postgres. Re-runs keep the region already in `fly.toml` unless you set this explicitly. | | `FLY_ORG` | `personal` | Fly org for both apps. They must share an org or the private network between them does not exist. | | `FLY_PG_IMAGE` | stock `postgres-flex` | Postgres image. Point it at a pgvector-enabled derivative to support knowledge bases. | ## Troubleshooting [#troubleshooting] Install [flyctl](https://fly.io/docs/flyctl/install/), then run `fly auth login`. The scripts accept either binary name, `flyctl` or `fly`. Expected. At [os.agno.com](https://os.agno.com), choose **Connect OS** → **Live**, enter your Fly 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/fly/env-sync.sh`. To use JWKS, bake or mount the file in the Fly Machine, set `JWT_JWKS_FILE` to its container path, then sync the variable. The script only manages names it generated. A different name means continuing would overwrite `fly.toml` and abandon that app. Restore the `agentos` placeholder (or an `agentos-*` name from a previous run), or tear down first with `./scripts/fly/down.sh`. Non-dev mode requires JWT verification configuration. Configured JWT credentials also enable validation in dev mode. Set `JWT_VERIFICATION_KEY` and sync. To use `JWT_JWKS_FILE`, first bake or mount a readable JWKS file at that container path, then sync the variable. `env-sync.sh` does not upload the file. For a private deployment using another auth layer, follow the credential-removal steps under [Production auth](#production-auth). The stock `postgres-flex` image has no pgvector; sessions and memory are unaffected. Set `FLY_PG_IMAGE` to a pgvector-enabled image and recreate the cluster. `up.sh` reuses an existing cluster, so tear down first with `./scripts/fly/down.sh`. See [Enable pgvector for knowledge bases](#customize). 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; it does not by itself prevent scheduled runs. For hosted MCP OAuth, set a public `AGENTOS_URL` and run `./scripts/fly/env-sync.sh`. Keep `auto_stop_machines = "off"` and `min_machines_running = 1` so the scheduler has a running process. Re-running `up.sh` restores the generated fly.dev URL; reapply a custom domain afterwards. A plain `fly deploy` created a second machine, and each runs its own scheduler. Deploy with the scripts; they pass `--ha=false`.