PsAgentAI/DEPLOY.md

PsAgentAI - Server Deployment

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

---

Prerequisites on the server

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

Enable journal if you want persistent logs (optional):

sudo apt install -y systemd-journal-remote

---

1) Copy the project to the server

Use git or scp/rsync. Example with git:

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

Adjust the path in the systemd service to the real directory:

nano psagentai.service
# change /home/marco/PsAgentAI/app to /opt/psagentai/app

The service uses User=marco by default. Create the user if it doesn't exist:

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

Or edit User= in the .service to an existing user on your VPS.

---

2) Configure .env

cp .env.example .env   # if example exists
nano .env

Fill in the required fields:

• TELEGRAM_BOT_TOKEN
• TELEGRAM_CHAT_ID
• AI_PROVIDER (openrouter, stepfun, qwencloud or llamacpp)
• DEFAULT_MODEL
• at least the AI key corresponding to the chosen provider

Optionally adjust:

• MIN_INTERVAL_MINUTES / MAX_INTERVAL_MINUTES
• MIN_MESSAGE_LINES

Important: on Telegram, send /start once to the bot before turning on the service, otherwise it won't be able to send starting messages.

---

3) Install dependencies

sudo apt install -y ffmpeg

```bash
chmod +x iniciar.sh
./iniciar.sh

This script creates the venv, installs dependencies and validates the .env variables.

If the above command doesn't install the expected ffmpeg version, also use:

sudo apt install -y ffmpeg

Voice recognition uses SpeechRecognition + pydub + ffmpeg.

---

4) Install the systemd service

# absolute path on your server
sudo nano /etc/systemd/system/psagentai.service

Minimum content:

[Unit]
Description=PsAgentAI
After=network.target

[Service]
Type=simple
User=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

Enable and start:

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

---

5) Useful commands

# status
sudo systemctl status psagentai

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

# restart after update
sudo systemctl restart psagentai

# stop
sudo systemctl stop psagentai

---

6) Future updates

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

---

7) Multiple users / VPSs

Each system instance is independent by Telegram chat ID.

For each new user/VPS:

1. Create the bot via @BotFather (/newbot) and get the token.
2. Copy the project to a separate directory, for example /opt/psagentai-user2.
3. Create your own .env with TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID and your AI keys.
4. Install dependencies with ./iniciar.sh.
5. Create a separate systemd service, ex: psagentai-user2.service, pointing to that directory.
6. Enable and start.

Recommended names to avoid conflicts:

• /opt/psagentai-user1/, /opt/psagentai-user2/
• psagentai-user1.service, psagentai-user2.service

---

8) .env variables

Variable	Required	Description
AI_PROVIDER	no	Preferred provider: openrouter, stepfun, qwencloud or llamacpp
TELEGRAM_BOT_TOKEN	yes	Telegram bot token
TELEGRAM_CHAT_ID	yes	User chat ID
DEFAULT_MODEL	yes	Default AI model
OPENROUTER_API_KEY	1 of the keys	OpenRouter key
STEPFUN_API_KEY	1 of the keys	StepFun key
QWENCLOUD_API_KEY	1 of the keys	QwenCloud key
MIN_INTERVAL_MINUTES	no	Minimum interval for proactive messages
MAX_INTERVAL_MINUTES	no	Maximum interval for proactive messages
MIN_MESSAGE_LINES	no	Minimum lines per agent message
AUTO_ENRICH_EVERY	no	Enriches profile every N messages
AUTO_IMPROVE_EVERY	no	Auto improvement every N messages
UPLOAD_CONTEXT_MAX_CHARS	no	Character limit of upload sent to AI (0 = no limit)
VISION_MODEL	no	AI model for image analysis
VISION_PROVIDER	no	Vision model provider (openrouter, stepfun, qwencloud)

---

Useful commands via Telegram

• /viewai — shows current AI provider and model
• /configai — interactively configures AI provider and model
• /viewvision — shows current vision provider and model
• /configvision — interactively configures vision model
• /about — displays system information, version, author and license

---

9) Important backups

Regularly backup the data files inside /app:

• user_profile.json
• agent_profile.json
• system_improvements.json
• uploads_metadata.json
• contexts/ folder
• workspace/ folder

Simple daily backup example:

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 contexts workspace

---

10) Security

• Never commit .env to the repository.
• Restrict permissions: chmod 600 .env.
• Use an exclusive user for each service instance.
• For greater isolation, run each instance in a separate Docker container or on distinct VMs.