Fly.io Reference

Fly app names are global, so up.sh generates a unique name (agentos-<suffix>), records it in fly.toml, and pairs it with a Postgres app named <app>-db. Later fly commands read the app name from fly.toml, so no --app flag is needed. Start with Deploy AgentOS on Fly.io for prerequisites and the first deployment.

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 default. Both deploy scripts pass fly deploy --ha=false because Fly otherwise creates two machines and doubles the application cost. fly.toml keeps the machine warm with auto_stop_machines = "off" and min_machines_running = 1; scheduled jobs stop when no machine is running. Validate schedule registration and MCP streams before adding machines.

Production auth

Token-Based Authorization protects AgentOS routes by default in 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 API access. Requests to protected AgentOS routes require a valid token. /, /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 Fly secrets, and redeploy. authorization=False disables AgentOS scope enforcement. Configured JWT environment variables continue to enable JWT validation. MCP OAuth remains active when MCP_CONNECT_SECRET is set. Only do this when another layer protects the service.

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, run ./scripts/fly/redeploy.sh.

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 ANTHROPIC_API_KEY in .env for local runs and .env.production for production, then regenerate pins:

./scripts/generate_requirements.sh

Rebuild locally with docker compose up -d --build. For production:

./scripts/fly/env-sync.sh
./scripts/fly/redeploy.sh

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 redeploy with ./scripts/fly/redeploy.sh.

Enable Slack

Set both variables in your env file:

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

Sync with ./scripts/fly/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.

Enable pgvector for knowledge bases

Fly’s stock postgres-flex image supports sessions and memory. Knowledge bases fail at CREATE EXTENSION until the database image includes pgvector. Build a derivative and publish it to a registry Fly can pull from. The commands below use a public Docker Hub repository:

mkdir -p postgres-pgvector
cat > postgres-pgvector/Dockerfile <<'EOF'
FROM flyio/postgres-flex:17
RUN apt-get install -y postgresql-17-pgvector
EOF

docker login
export PG_IMAGE="<docker-hub-user>/agentos-postgres-pgvector:17"
docker buildx build --platform linux/amd64 --push \
  -t "$PG_IMAGE" postgres-pgvector

export FLY_PG_IMAGE="$PG_IMAGE"
./scripts/fly/up.sh

FLY_PG_IMAGE applies when the Postgres cluster is created. up.sh reuses an existing cluster, so switching later requires ./scripts/fly/down.sh, which deletes the app, database, and all stored data. Then export FLY_PG_IMAGE and provision again.

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.
`RUNTIME_ENV`	No	`prd`	`dev` sets `authorization=False`, which disables AgentOS scope enforcement. Configured JWT environment variables continue to enable JWT validation. Compose sets `dev` locally; keep `prd` on Fly.
`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://<app>.fly.dev`. Scheduled jobs never fire if it stays at the default in production. 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.
`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. `up.sh` sets these as Fly secrets pointing at `<app>-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

flyctl: command not found

Install flyctl, then run fly auth login. The scripts accept either binary name, flyctl or fly.

up.sh pauses asking for a JWT key

Expected. Mint the key at os.agno.com: connect your OS (Connect OS → Live, enter your Fly 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/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.

up.sh exits: fly.toml carries an app name this script doesn't manage

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.

App fails to start in production

AgentOS scope enforcement is on whenever RUNTIME_ENV is not dev. 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. To disable JWT, set authorization=False in app/main.py, remove both JWT variables from the Fly secrets, and redeploy. MCP OAuth remains active when MCP_CONNECT_SECRET is set.

Knowledge bases fail at CREATE EXTENSION

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.

Scheduled jobs never fire

AGENTOS_URL may still be the localhost default. up.sh sets it to https://<app>.fly.dev automatically; for a custom domain or tunnel, set it by hand and run ./scripts/fly/env-sync.sh. Re-running up.sh resets a hand-set value to the generated fly.dev URL, so re-pin it afterwards. The other cause is the machine scaling to zero: keep auto_stop_machines = "off" and min_machines_running = 1 in fly.toml.

A second Fly Machine appeared

A plain fly deploy enables Fly’s default HA topology. Deploy with the scripts to keep one machine; they pass --ha=false. AgentOS claims due schedules through PostgreSQL. This template has not been validated for simultaneous schedule registration and MCP streams across multiple machines.

Get Started

Starters

Apps

Agno CLI

Fly.io Reference

Manage

Production auth

Customize

Format, validate, and run evals

Environment variables

Troubleshooting

​Manage

​Production auth

​Customize

​Format, validate, and run evals

​Environment variables

​Troubleshooting

Manage

Production auth

Customize

Format, validate, and run evals

Environment variables

Troubleshooting