Modal 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/modal/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/modal/env-sync.sh

env-sync.sh rewrites the secret with the new provider key and redeploys. The redeploy rebuilds the image, so the new dependency ships with it.

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/modal/redeploy.sh.

Set both variables in your env file:

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

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

Install the CLI with pip install modal or uv tool install modal, then run modal token new.

Install it with brew install neonctl or npm i -g neonctl, then run neonctl auth.

Neon projects are org-scoped, so neonctl projects create asks which organization to use and hangs non-interactive runs. Set NEON_ORG_ID in .env.production (find yours with neonctl orgs list) and re-run ./scripts/modal/up.sh; the script passes it as --org-id so the deploy runs unattended.

Expected. At os.agno.com, choose Connect OS → Live, enter your modal.run 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/modal/env-sync.sh. To use JWKS, add the file to the Docker build context or configure a Modal mount, set JWT_JWKS_FILE to its container path, then deploy.

Non-dev mode requires JWT verification configuration. Configured JWT credentials also enable validation in dev mode. Set JWT_VERIFICATION_KEY and sync. For JWT_JWKS_FILE, first make the file available inside the Modal image or through a mount, then set its container path and sync. For a private deployment using another auth layer, follow the credential-removal steps under Production auth.

Secrets are read at container start, so rewriting the secret alone changes nothing. ./scripts/modal/env-sync.sh does both steps: it rewrites agentos-secrets and redeploys to roll the container.

AGENTOS_URL is still the localhost default. up.sh sets it to your modal.run URL automatically; for a custom domain or tunnel, set it by hand and run ./scripts/modal/env-sync.sh.

down.sh deletes the Neon project but leaves NEON_PROJECT_ID and the DB_* values in your env file, so up.sh thinks a database still exists. Delete those lines and re-run ./scripts/modal/up.sh to provision a fresh one.

The script only declares success once the app no longer shows as running in modal app list and the project is gone from neonctl projects list. Check both, then re-run it or finish by hand: modal app stop agentos and neonctl projects delete <project-id>.