Scale-to-Zero Gateway

Suspend the gateway when nothing is happening and wake on the next message — pay only for active time

from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful.")
# Scale-to-zero idles the runtime until the next user message wakes the agent
agent.start("Anyone there?")

A scale-to-zero policy quiesces the gateway and (optionally) suspends the compute host when no turn is in flight and no background work is pending, then wakes on the next inbound message.

The user is idle; the gateway scales workers to zero and wakes them when the next message arrives.

Quick Start

1. Simplest setup — 5-minute idle timeout

   from praisonaiagents import Agent
   from praisonai.bots import BotOS, Bot
   from praisonaiagents.gateway import ScaleToZeroPolicy
   
   agent = Agent(name="assistant", instructions="Help users")
   
   botos = BotOS(
       bots=[Bot("telegram", agent=agent)],
       idle_policy=ScaleToZeroPolicy(
           idle_timeout_minutes=5,
           wake_url="https://my-bot.fly.dev/_wake",
       ),
   )
   botos.run()

   The gateway now ticks every 30 seconds. After 5 minutes of silence with no turns in flight, it stops transports and calls your _on_quiesce hook (if set). The next POST /_wake brings it back.

2. Tighter timeout for more aggressive savings

   from praisonaiagents import Agent
   from praisonai.bots import BotOS, Bot
   from praisonaiagents.gateway import ScaleToZeroPolicy
   
   agent = Agent(name="assistant", instructions="Help users")
   
   idle_policy = ScaleToZeroPolicy(
       idle_timeout_minutes=2,
       wake_url="https://my-bot.fly.dev/_wake",
   )
   
   botos = BotOS(
       bots=[Bot("telegram", agent=agent)],
       idle_policy=idle_policy,
   )
   botos.run()

3. With a compute-host suspend hook (Fly / Modal)

   from praisonaiagents import Agent
   from praisonai.bots import BotOS, Bot
   from praisonaiagents.gateway import ScaleToZeroPolicy
   
   agent = Agent(name="assistant", instructions="Help users")
   
   policy = ScaleToZeroPolicy(
       idle_timeout_minutes=5,
       wake_url="https://my-bot.fly.dev/_wake",
   )
   
   async def suspend_host():
       # Tell Fly Machines / Modal to suspend this VM
       # e.g. call the Fly Machines stop API here
       pass
   
   botos = BotOS(bots=[Bot("telegram", agent=agent)], idle_policy=policy)
   botos._on_quiesce = suspend_host  # runs AFTER transports are cleanly down
   botos.run()

4. Primary runtime — enable via gateway.yaml

   Scale-to-zero is wired into the primary WebSocketGateway (praisonai gateway start) through a lifecycle: block.

   # gateway.yaml
   lifecycle:
     scale_to_zero:
       enabled: true
       idle_minutes: 10
       wake_url: "https://my-bot.fly.dev/_wake"   # optional (see self-wake note)

   praisonai gateway start --config gateway.yaml

   The gateway serves normally, then quiesces after idle_minutes of no inbound or in-flight work. The next client frame wakes it.

5. Primary runtime — enable via CLI flags (no YAML)

   praisonai gateway start --scale-to-zero --idle-minutes 10

   The flags synthesize a lifecycle: block, so CLI overrides win over gateway.yaml. No wake_url is needed — the listening socket is an inherent self-wake path.

How It Works

Key behaviours:

Configuration Options

ScaleToZeroPolicy constructor

from praisonaiagents.gateway import ScaleToZeroPolicy

policy = ScaleToZeroPolicy(
    idle_timeout_minutes=5.0,
    wake_url="https://my-bot.example.com/_wake",
    enabled=True,
)

Properties on the instance:

BotOS — idle policy field

BotOS runtime activity hooks

Imports

from praisonaiagents.gateway import (
    IdleDecision,
    GatewayIdlePolicyProtocol,
    GatewayIdlePolicy,          # backward-compat alias
    ScaleToZeroPolicy,
)

lifecycle.scale_to_zero: YAML block (WebSocketGateway)

The primary WebSocketGateway reads scale-to-zero from a lifecycle: block at the top level of gateway.yaml or nested under gateway:.

lifecycle:
  scale_to_zero:
    enabled: true
    idle_minutes: 10
    wake_url: "https://my-bot.fly.dev/_wake"

CLI flags (WebSocketGateway)

CLI flags win over YAML — they are folded into the lifecycle: block before the policies are built.

Observability

When scale-to-zero (or a drain marker watch) is configured, health() adds a lifecycle object so operators can see the state without scraping logs.

{
  "status": "healthy",
  "uptime": 3600,
  "agents": 2,
  "sessions": 5,
  "clients": 3,
  "lifecycle": {
    "scale_to_zero": true,
    "dormant": false,
    "drain_marker_watch": false
  }
}

The lifecycle field is emitted only when a lifecycle feature is configured, so always-on gateways are unchanged.

Hot Reload

Enabling or disabling scale-to-zero via a gateway.yaml reload takes effect without a full process restart. The gateway rebuilds the pure policy and cancels or relaunches only the idle loop whose enablement changed — an unchanged lifecycle: block leaves running tasks untouched. See Gateway Hot Reload.

Common Patterns

Fly Machines auto-suspend

import httpx
from praisonaiagents import Agent
from praisonai.bots import BotOS, Bot
from praisonaiagents.gateway import ScaleToZeroPolicy

agent = Agent(name="assistant", instructions="Help users")

policy = ScaleToZeroPolicy(
    idle_timeout_minutes=5,
    wake_url="https://my-bot.fly.dev/_wake",
)

async def suspend_fly_machine():
    # Fly Machines: POST /v1/apps/{app}/machines/{machine}/stop
    async with httpx.AsyncClient() as client:
        await client.post(
            "https://api.machines.dev/v1/apps/my-bot/machines/MY_MACHINE_ID/stop",
            headers={"Authorization": f"Bearer {FLY_API_TOKEN}"},
        )

botos = BotOS(bots=[Bot("telegram", agent=agent)], idle_policy=policy)
botos._on_quiesce = suspend_fly_machine

# Your /_wake route must call botos.wake()
botos.run()

The /_wake route in your web framework calls await botos.wake(), which reconnects all transports and the gateway is live again within seconds.

Env-var kill switch

import os
from praisonaiagents import Agent
from praisonai.bots import BotOS, Bot
from praisonaiagents.gateway import ScaleToZeroPolicy

agent = Agent(name="assistant", instructions="Help users")

policy = ScaleToZeroPolicy(
    enabled=os.getenv("SCALE_TO_ZERO") == "1",
    idle_timeout_minutes=5,
    wake_url=os.getenv("WAKE_URL", ""),
)

botos = BotOS(bots=[Bot("telegram", agent=agent)], idle_policy=policy)
botos.run()

Set SCALE_TO_ZERO=1 in production. In dev, leave it unset — the policy stays disabled and the gateway runs always-on with zero overhead.

Tighter timeout for prototype bots

from praisonaiagents import Agent
from praisonai.bots import BotOS, Bot
from praisonaiagents.gateway import ScaleToZeroPolicy

agent = Agent(name="demo", instructions="Quick demo bot")

policy = ScaleToZeroPolicy(
    idle_timeout_minutes=1,           # quiesce after 1 min idle
    wake_url="https://demo.example.com/_wake",
)

botos = BotOS(bots=[Bot("telegram", agent=agent)], idle_policy=policy)
botos.run()

Use 1 minute for disposable demo bots. Bump to 5+ minutes for production where users expect instant responses.

Best Practices

Scheduled delivery when the gateway is asleep

An enabled scheduled job keeps the gateway resident. If you instead run praisonai schedule tick from OS cron with the gateway scaled to zero, delivery still lands out of process — the tick falls back to a per-platform standalone HTTPS sender for Telegram, Slack, Discord, WhatsApp, and Signal, using each platform’s own env ({PLATFORM}_BOT_TOKEN, or the WhatsApp / Signal env vars). Each send is retried in-process on transient failures with exponential backoff, so a 429 or a brief 5xx does not silently drop the brief. See Out-of-process delivery.

Related