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](#prerequisites)
2. [Copy Project to Server](#1-copy-project-to-server)
3. [Configure Environment](#2-configure-environment)
4. [Install Dependencies](#3-install-dependencies)
5. [Install systemd Service](#4-install-systemd-service)
6. [Service Management](#5-service-management)
7. [Updates](#6-updates)
8. [Multi-User Deployment](#7-multi-user-deployment)
9. [Environment Variables Reference](#8-environment-variables-reference)
10. [Backups](#9-backups)
11. [Security](#10-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)

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

Optional: enable persistent journal logs:

```bash
sudo apt install -y systemd-journal-remote
```

---

## 1) Copy Project to Server

### Using git

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

### Using scp/rsync

```bash
# 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

```bash
# 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 |
| `WEB_SEARCH_SCRAPE_ENABLED` | `true` | Fetch page content for search results (uses headless browser fallback) |
| `WEB_SEARCH_SCRAPE_CACHE_TTL` | `3600` | Cache TTL for scraped pages in seconds |
| `WEB_SEARCH_SCRAPE_MAX_CHARS` | `15000` | Max characters per scraped page |
| `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

```bash
# 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:

```bash
sudo apt install -y ffmpeg
```

> Voice recognition requires `SpeechRecognition` + `pydub` + `ffmpeg`.

---

## 4) Install systemd Service

Create the service file:

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

```ini
[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:

```bash
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:

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

---

## 5) Service Management

```bash
# 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

```bash
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](https://t.me/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:

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

```ini
[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:

```bash
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 |
| `WEB_SEARCH_SCRAPE_ENABLED` | `true` | Fetch page content for search results (uses headless browser fallback for JS-rendered sites) |
| `WEB_SEARCH_SCRAPE_CACHE_TTL` | `3600` | Cache TTL for scraped pages in seconds |
| `WEB_SEARCH_SCRAPE_MAX_CHARS` | `15000` | Max characters per scraped page |
| `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

```bash
# 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

```bash
sudo crontab -e
```

Add:

```cron
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](https://syspanel.com.br)
- Author: Marco A. S. Costa
- Email: contato@syspanel.com.br
- License: Proprietary for syspanel.com.br