PsAgentAI/DEPLOY.md

PsAgentAI - Server Deployment

Deploy PsAgentAI as a systemd service on Debian/Ubuntu to run 24/7 on a VPS.

Table of Contents

1. Prerequisites
2. Copy Project to Server
3. Configure Environment
4. Install Dependencies
5. Install systemd Service
6. Service Management
7. Updates
8. Multi-User Deployment
9. Environment Variables Reference
10. Backups
11. Security

---

Prerequisites

A fresh Debian/Ubuntu server with:

• python3, python3-venv, python3-pip
• git (if cloning from repository)
• ffmpeg (for voice message processing)
• systemd-journal-remote (optional, for persistent logs)

sudo apt update
sudo apt install -y python3 python3-venv python3-pip git ffmpeg

Optional: enable persistent journal logs:

sudo apt install -y systemd-journal-remote

---

1) Copy Project to Server

Using git

cd /opt
sudo git clone <REPOSITORY_URL> psagentai
sudo chown -R $USER:$USER /opt/psagentai
cd /opt/psagentai/app

Using scp/rsync

# From your local machine:
scp -r psagentai/ user@server:/opt/psagentai/

Adjust paths in the systemd service file to match your actual installation directory.

---

2) Configure Environment

# If .env.example exists, copy it:
cp .env.example .env

# Otherwise create .env manually:
nano .env

Required settings

Variable	Description
TELEGRAM_BOT_TOKEN	Token from @BotFather
TELEGRAM_CHAT_ID	Your Telegram chat ID
AI_PROVIDER	openrouter, stepfun, qwencloud or llamacpp
DEFAULT_MODEL	Model identifier for the chosen provider
OPENROUTER_API_KEY or STEPFUN_API_KEY or QWENCLOUD_API_KEY	At least one AI provider key

Optional settings

Variable	Default	Description
MIN_INTERVAL_MINUTES	3	Minimum minutes between proactive messages
MAX_INTERVAL_MINUTES	30	Maximum minutes between proactive messages
MIN_MESSAGE_LINES	3	Minimum lines per agent message
WEB_SEARCH_ENABLED	true	Enable automatic web search
WEB_SEARCH_MAX_RESULTS	5	Max web search results
VISION_MODEL	meta-llama/llama-4-maverick-17b-128b-instruct	Vision model
VISION_PROVIDER	auto	Vision provider
AUTO_ENRICH_EVERY	2	Profile auto-enrichment frequency (0 = disabled)
AUTO_IMPROVE_EVERY	20	Auto-improvement frequency (0 = disabled)
UPLOAD_CONTEXT_MAX_CHARS	8000	Upload context limit (0 = unlimited)

Important

: Before starting the service, send /start once to the bot in Telegram. This allows the bot to resolve the chat and send proactive messages later.

---

3) Install Dependencies

# Install system dependency for voice processing
sudo apt install -y ffmpeg

# Make setup script executable and run it
chmod +x iniciar.sh
./iniciar.sh

The setup script will:

1. Create a Python virtual environment (venv/)
2. Upgrade pip
3. Install Python dependencies from requirements.txt
4. Validate .env configuration
5. Start the agent

If ffmpeg was not installed by the system package manager, install it separately:

sudo apt install -y ffmpeg

Voice recognition requires SpeechRecognition + pydub + ffmpeg.

---

4) Install systemd Service

Create the service file:

sudo nano /etc/systemd/system/psagentai.service

[Unit]
Description=PsAgentAI
After=network.target

[Service]
Type=simple
User=marco
Group=marco
WorkingDirectory=/opt/psagentai/app
Environment="PATH=/opt/psagentai/app/venv/bin:/usr/local/bin:/usr/bin:/bin"
ExecStart=/opt/psagentai/app/venv/bin/python3 /opt/psagentai/app/psagentai_agent.py
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Adjust the following to match your setup:

• User= and Group= — the user that will run the service
• WorkingDirectory= — absolute path to the app/ directory
• ExecStart= — absolute path to the Python executable and agent script

Create the service user if needed:

sudo useradd -m -s /bin/bash marco || true
sudo usermod -aG sudo marco

Or change User= and Group= to an existing user on your VPS.

Reload systemd and enable the service:

sudo systemctl daemon-reload
sudo systemctl enable psagentai
sudo systemctl start psagentai

---

5) Service Management

# Check status
sudo systemctl status psagentai

# View real-time logs
sudo journalctl -u psagentai -f

# Stop the service
sudo systemctl stop psagentai

# Restart after changes
sudo systemctl restart psagentai

# Disable auto-start
sudo systemctl disable psagentai

---

6) Updates

cd /opt/psagentai/app
git pull
./iniciar.sh
sudo systemctl restart psagentai

---

7) Multi-User Deployment

Each PsAgentAI instance is independent by Telegram chat ID. To run multiple instances:

1. Create a separate bot via @BotFather (/newbot) for each user
2. Copy the project to a separate directory for each instance, e.g.:
   • /opt/psagentai-user1/
   • /opt/psagentai-user2/
3. Create a dedicated .env for each instance with its own TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID, and AI keys
4. Run ./iniciar.sh in each directory to set up the environment
5. Create a separate systemd service file for each instance:

# Example for user2
sudo nano /etc/systemd/system/psagentai-user2.service

[Unit]
Description=PsAgentAI - User 2
After=network.target

[Service]
Type=simple
User=marco
Group=marco
WorkingDirectory=/opt/psagentai-user2/app
Environment="PATH=/opt/psagentai-user2/app/venv/bin:/usr/local/bin:/usr/bin:/bin"
ExecStart=/opt/psagentai-user2/app/venv/bin/python3 /opt/psagentai-user2/app/psagentai_agent.py
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

6. Enable and start each service:

sudo systemctl daemon-reload
sudo systemctl enable psagentai-user2
sudo systemctl start psagentai-user2

Recommended naming convention to avoid conflicts:

• Directories: /opt/psagentai-user1/, /opt/psagentai-user2/
• Services: psagentai-user1.service, psagentai-user2.service

---

8) Environment Variables Reference

Telegram

Variable	Required	Description
TELEGRAM_BOT_TOKEN	Yes	Telegram bot token from @BotFather
TELEGRAM_CHAT_ID	Yes	Target chat ID for proactive messages

AI Providers

Variable	Required	Description
AI_PROVIDER	Yes	Preferred provider: openrouter, stepfun, qwencloud or llamacpp
DEFAULT_MODEL	Yes	Model identifier (provider-specific)
OPENROUTER_API_KEY	Conditional	Required for OpenRouter
OPENROUTER_API_URL	No	OpenRouter API base URL
STEPFUN_API_KEY	Conditional	Required for StepFun
STEPFUN_API_URL	No	StepFun API base URL
QWENCLOUD_API_KEY	Conditional	Required for QwenCloud
QWENCLOUD_API_URL	No	QwenCloud API base URL
LLAMA_CPP_API_URL	No	llama.cpp server URL (default: http://localhost:8080/v1)
FALLBACK_MODELS	No	Comma-separated fallback models

Behavior Tuning

Variable	Default	Description
MIN_INTERVAL_MINUTES	3	Minimum minutes between proactive messages
MAX_INTERVAL_MINUTES	30	Maximum minutes between proactive messages
MIN_MESSAGE_LINES	3	Minimum lines per agent message
MAX_HISTORY_LENGTH	50	Max messages in conversation context
UPLOAD_CONTEXT_MAX_CHARS	8000	Max chars from uploads sent to AI (0 = unlimited)
WEB_SEARCH_ENABLED	true	Enable automatic web search
WEB_SEARCH_MAX_RESULTS	5	Maximum search results returned
AUTO_ENRICH_EVERY	2	Auto-enrich profiles every N messages (0 = disabled)
AUTO_IMPROVE_EVERY	20	Auto-improve system every N messages (0 = disabled)

Vision / Image Analysis

Variable	Default	Description
VISION_MODEL	meta-llama/llama-4-maverick-17b-128b-instruct	Model for image analysis
VISION_PROVIDER	auto	Provider for vision model

Persistence

Variable	Default	Description
USER_PROFILE_FILE	user_profile.json	User profile file path
AGENT_PROFILE_FILE	agent_profile.json	Agent profile file path
CONTEXTS_DIR	contexts	Conversation context directory

---

9) Backups

Regularly back up the data files in the app/ directory:

• user_profile.json — user profile data
• agent_profile.json — agent personality and traits
• system_improvements.json — auto-improvement history
• uploads_metadata.json — uploaded files index
• config.json — schedule configuration
• contexts/ — conversation history by date
• workspace/ — created and edited files

Daily backup example

# Create backups directory
sudo mkdir -p /root/backups

# Run daily backup
BACKUP_FILE="/root/backups/psagentai-$(date +%F).tar.gz"
tar czf "$BACKUP_FILE" -C /opt/psagentai/app \
  user_profile.json \
  agent_profile.json \
  system_improvements.json \
  uploads_metadata.json \
  config.json \
  contexts \
  workspace

echo "Backup created: $BACKUP_FILE"

Automated backup with cron

sudo crontab -e

Add:

0 2 * * * /usr/bin/tar czf /root/backups/psagentai-$(date +\%F).tar.gz -C /opt/psagentai/app user_profile.json agent_profile.json system_improvements.json uploads_metadata.json config.json contexts workspace

This creates a backup every day at 2:00 AM.

---

10) Security

• Never commit .env to version control. Add it to .gitignore.
• Restrict permissions: chmod 600 .env to prevent other users from reading secrets.
• Use dedicated users: Run each instance under its own system user for isolation.
• Firewall: Only expose necessary ports (typically only outbound HTTPS is needed).
• API keys: Rotate keys periodically and monitor usage for anomalies.
• Path validation: The agent validates file paths to prevent directory traversal attacks.
• Sensitive data: Emails and phone numbers in profiles are preserved but not exposed in logs.

---

Useful Telegram Commands for Administration

• /viewai — Check current AI provider and model
• /configai — Change AI provider/model on the fly
• /viewvision — Check vision configuration
• /configvision — Change vision model on the fly
• /debug — View system debug information
• /reload — Reload .env without restarting the service
• /timezone — Check server timezone

---

Support

• System developed by: Syspanel.com.br
• Author: Marco A. S. Costa
• Email: contato@syspanel.com.br
• License: Proprietary for syspanel.com.br