marcocosta10000
6b11f05dab
- Rewrite README.md, DEPLOY.md and RULES.md in English - Translate module docstring, license string and inline comments - Rename Portuguese state variables (is_agendamento, is_useragenda, is_configia) to English equivalents (is_schedule, is_dailyroutine, is_configai) - Replace Portuguese web-search and file-creation trigger phrases with English keywords
240 lines
5.5 KiB
Markdown
240 lines
5.5 KiB
Markdown
# 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.
|