Fly.io Reference

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

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:

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:

  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:

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:

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

Agno ships 100+ toolkits. See Toolkits.

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:

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.

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:

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.

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

Expected. At 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.

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.

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.