# PsAgentAI - Server Deployment

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

---

## Prerequisites on the server

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

Enable journal if you want persistent logs (optional):

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

---

## 1) Copy the project to the server

Use git or scp/rsync. Example with git:

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

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

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

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

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

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

---

## 4) Install the systemd service

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

Minimum content:

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

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

---

## 5) Useful commands

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

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

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