Skip to main content
The gateway now ships in the praisonai-bot package. praisonai serve gateway still works exactly as documented here; for a standalone install see praisonai-bot Migration.
After an in-place update — git pull, pip install -U, or auto-update on a durable volume — a /model switch previously crashed with a cryptic ImportError from a lazy import loaded after startup. The code-skew guard detects the mismatch and refuses the operation with a clear message. 
from praisonaiagents import Agent

agent = Agent(name="ops", instructions="Help operators switch gateway models safely.")
agent.start("/model gpt-4o")
The user sends /model after code on disk changed; the skew guard blocks the switch until the gateway restarts with the new build.

​
Quick Start

1

The guard is on by default

No configuration needed. If someone runs git pull while the gateway is running and then sends /model gpt-4o, they’ll see:
⚠️ Gateway code changed on disk since it started (2aa28d1 → def5678).
Restart the gateway to apply updates before switching models.
2

Opt out if needed

from praisonai.bots import Bot
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Help users")
bot = Bot("telegram", agent=agent)
session_manager = bot.session_manager
session_manager.code_skew_guard = False  # disable the guard
bot.run()
3

Update code in place and try /model

With the bot running, update the code on disk (git pull) then ask the bot to switch models:
/model gpt-4o
⚠️ Gateway code changed on disk since it started (2aa28d1 → def5678). Restart the gateway to apply updates before switching models.
Restart the process, then try again — the switch will succeed.
4

Opt out of the guard (optional)

For CI runners or environments where in-place updates are deliberate:
from praisonaiagents import Agent

agent = Agent(name="Bot", instructions="You are a helpful assistant.")
session_manager = agent.session_manager
session_manager.code_skew_guard = False
agent.start("Hello")

​
How It Works

​
Fingerprint Sources

The fingerprint is determined by read_code_fingerprint(), which tries these in order:
  1. Git SHA — git rev-parse HEAD in the checkout directory (most reliable)
  2. Newest .py mtime — modification time of the most recently changed Python file (fallback when git is unavailable)
  3. None — if both fail, the fingerprint is unknown
When a fingerprint is None, detect_code_skew returns False (fail-open) — the guard never blocks when it can’t determine the code state.

​
Configuration Options

SettingTypeDefaultDescription
session_manager.code_skew_guardboolTrueEnable or disable the guard for all hot operations on this session manager
The guard is fail-open: when fingerprints can’t be determined (no git, no .py files found), it permits the operation rather than blocking it.

​
User-Facing Message

When the guard detects a skew, the user sees a message like: 
⚠️ Gateway code changed on disk since it started (2aa28d1 → def5678).
Restart the gateway to apply updates before switching models.
The fingerprints shown are the boot fingerprint and the current disk fingerprint, making it easy to confirm which version is running vs. which version is on disk.

​
Common Patterns

​
Automated deployment with code-skew detection

#!/bin/bash
# After deploying a new version:
git pull
pip install -U praisonai

# The running gateway will now detect skew on the next /model command
# and prompt users to restart — no silent ImportError.
# Graceful restart:
systemctl restart praisonai-gateway

​
Check skew before a scheduled model rotation

from praisonaiagents.gateway import read_code_fingerprint, detect_code_skew

boot_fp = read_code_fingerprint()   # saved at startup
current_fp = read_code_fingerprint()

if detect_code_skew(boot_fp, current_fp):
    # Restart before rotating models
    raise RuntimeError("Code skew detected — restart the gateway first")

​
Best Practices

The guard catches this automatically, but a clean restart is always safer than a hot operation on stale imports. Plan deployments to restart the gateway after git pull / pip install.
The guard prefers git SHA for fingerprinting. Deployments from a proper git checkout give better fingerprint accuracy than bare file installs.
If fingerprinting fails (e.g. no git, no .py files), the guard permits the operation. This prevents blocking legitimate use in non-git environments while still protecting typical deployments.
The guard only fires on specific hot operations like /model. Normal message processing continues unaffected — users can still chat; only model-switch commands are blocked.

Gateway Exit Codes

Signal transient vs. fatal failures to supervisors

Gateway Hot Reload

Reload configuration without restarting

Bot Commands

Built-in and custom /commands for bots

Gateway Overview

Gateway architecture and startup sequence