Skip to main content
The Modal app is agentos, served as one always-warm container. Configuration lives in the agentos-secrets Modal secret, and the database is a Neon Postgres project named agentos.

​
Manage

TaskCommand
Deploy code changes./scripts/modal/redeploy.sh
Sync env variables./scripts/modal/env-sync.sh (defaults to .env.production; pass .env to sync that instead)
Tail logsmodal app logs agentos
List apps and statusmodal app list
Tear down./scripts/modal/down.sh (add --yes to skip the confirmation)
modal_app.py pins min_containers=1 and max_containers=1. The always-warm container keeps the in-process scheduler and MCP streams alive, and the cap stops two schedulers from double-firing every cron. Keep both settings.

​
Production auth

Token-Based Authorization is on by default. Without a JWT_VERIFICATION_KEY or JWT_JWKS_FILE, the app refuses to serve traffic in production. The platform’s job is to keep your data private, so the safe default is refuse to start. Token-Based Auth gives you three things:
  1. No public access. The server rejects requests without a valid token.
  2. Per-request identity. Middleware parses the token and extracts the user_id, session_id, and custom claims. Each request is tied to a user and session, giving you auditability and traceability.
  3. Granular permissions. User tokens can run an agent and view their own sessions. Admin tokens read everyone’s sessions and test any agent.
To opt out (not recommended), set authorization=False in app/main.py and redeploy. Use this only inside a private VPC behind another auth layer. Without it, anyone who guesses your modal.run URL can access your platform.

​
Customize

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,
)
Register it in app/main.py:
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/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(
    ...
    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 Agent Builder; change the agent= argument in app/main.py to point at another agent. See Slack setup.
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.

​
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
TaskCommand
Format./scripts/format.sh
Lint and type-check./scripts/validate.sh
Run smoke evalspython -m evals --tag smoke
./scripts/mcp_check.sh runs inside the container, so it needs no venv.

​
Environment variables

VariableRequiredDefaultDescription
OPENAI_API_KEYYes-Models and embeddings.
RUNTIME_ENVNoprddev disables JWT. Compose sets it for local. Never put it in an env file that syncs to Modal, or production deploys unauthenticated.
JWT_VERIFICATION_KEYProduction-Public key from os.agno.com. Quote the value so the multi-line PEM parses as one variable.
JWT_JWKS_FILEProduction-Path to a JWKS file. Alternative to JWT_VERIFICATION_KEY. up.sh carries it into the agentos-secrets secret when set.
MCP_CONNECT_SECRETNogenerated by up.shOAuth 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_KEYNogeneratedOptional 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_URLNohttp://127.0.0.1:8000Scheduler base URL. up.sh sets it to your modal.run URL. Scheduled jobs never fire if it stays at the default in production. Also the public origin OAuth metadata derives from when MCP_CONNECT_SECRET is set.
ENABLE_DEPLOY_CHECKNoTrueDaily deployment-check cron.
ENABLE_SCHEDULED_EVALSNoFalseDaily run-evals cron. Uses model calls.
EVALS_TAGNosmokeEval tag the run-evals workflow runs.
EVALS_CASE_TIMEOUT_SECONDSNo90Per-case timeout for run-evals runs.
EVALS_SUITE_TIMEOUT_SECONDSNo900Whole-suite timeout for run-evals runs.
PARALLEL_API_KEYNo-WebSearch uses the Parallel SDK when set, keyless MCP otherwise.
SLACK_BOT_TOKENNo-Set with the signing secret to enable Slack.
SLACK_SIGNING_SECRETNo-Set with the bot token to enable Slack.
DB_HOST / DB_PORT / DB_USER / DB_PASS / DB_DATABASENomatches composePostgres connection. up.sh fills these from your Neon project.
DB_DRIVERNopostgresql+psycopgSQLAlchemy driver.
NEON_PROJECT_IDNowritten by up.shIdentifies the Neon project so down.sh can delete it. env-sync.sh skips NEON_* keys; they never sync to the app.
NEON_ORG_IDNo-Neon organization for unattended deploys. neonctl projects create prompts for an org and hangs non-interactive runs; set it (find yours with neonctl orgs list) so up.sh can pass --org-id.
PGSSLMODENo-The deploy scripts set it to require in the Modal secret. Neon requires TLS, and libpq honors the variable, so the app needs no change.
AGNO_DEBUGNoFalseVerbose Agno logs. Compose sets it for dev.
WAIT_FOR_DBNoFalseIf True, the entrypoint blocks on the database before starting. Compose sets it.

​
Troubleshooting

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. Mint the key at os.agno.com: connect your OS (Connect OS → Live, enter your modal.run URL), then turn on Token-Based Authorization (JWT) under Settings → OS & Security and paste the full PEM. To do it later, skip the prompt, add JWT_VERIFICATION_KEY or JWT_JWKS_FILE to .env.production, and run ./scripts/modal/env-sync.sh.
JWT auth is on whenever RUNTIME_ENV is not dev. Set JWT_VERIFICATION_KEY or JWT_JWKS_FILE and sync. To opt out inside a private VPC behind another auth layer, set authorization=False in app/main.py.
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>.