zCode-CLI-X/INSTALLATION.md

zCode CLI X - Installation & Setup Guide

Prerequisites

Required

• Node.js ≥ 20.0.0 (Download)
• npm ≥ 9.0.0 (comes with Node.js)
• Git (for version control)
• systemd (for 24/7 service on Linux)
• ffmpeg (for voice I/O)
• Python 3.8+ (for Vosk STT)

Optional

• SSL certificate (for HTTPS webhook)
• Domain name (for custom webhook URL)
• Docker (for containerized deployment - coming soon)

---

Quick Start (5 Minutes)

1. Clone Repository

git clone https://github.rommark.dev/admin/zCode-CLI-X.git
cd zCode-CLI-X

2. Install Dependencies

npm install

3. Configure Environment

cp .env.example .env
nano .env

Edit .env with your credentials:

# Z.AI Configuration (Coding Plan)
GLM_BASE_URL=https://api.z.ai/api/coding/paas/v4
ZAI_API_KEY=your_zai_api_key_here

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
TELEGRAM_ALLOWED_USERS=your_telegram_id,friend_id
ZCODE_WEBHOOK_URL=https://your-domain.com/telegram/webhook

4. Test Run

# Test as CLI (temporary session)
node bin/zcode.js

# Test as bot (24/7)
node bin/zcode.js --no-cli

5. Install as Systemd Service

# Copy service file
cp scripts/zcode.service ~/.config/systemd/user/

# Reload systemd
systemctl --user daemon-reload

# Enable and start service
systemctl --user enable zcode
systemctl --user start zcode

# Check status
systemctl --user status zcode

# View logs
journalctl --user -u zcode -f

✅ Done! Your bot is now running 24/7.

---

Detailed Setup

Step 1: Install Node.js

Ubuntu/Debian

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version  # Should show v20.x or higher
npm --version   # Should show 9.x or higher

macOS (Homebrew)

brew install node@20
node --version
npm --version

CentOS/RHEL

curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs
node --version
npm --version

Step 2: Install ffmpeg (for Voice I/O)

Ubuntu/Debian

sudo apt-get update
sudo apt-get install -y ffmpeg
ffmpeg -version  # Verify installation

macOS

brew install ffmpeg
ffmpeg -version

CentOS/RHEL

sudo yum install -y ffmpeg
ffmpeg -version

Step 3: Install Python & Vosk (for Voice STT)

Install Python 3.8+

# Ubuntu/Debian
sudo apt-get install -y python3 python3-pip

# macOS
brew install python

# Verify
python3 --version  # Should show 3.8+
pip3 --version

Install Vosk Model

# Create model directory
mkdir -p ~/vosk-models

# Download small model (68MB, ~95% accuracy)
cd ~/vosk-models
wget https://alphacephei.com/vosk-models/vosk-model-small-0.15.zip
unzip vosk-model-small-0.15.zip

# Verify
ls -la vosk-model-small-0.15/  # Should show model files

Install Vosk Python Package

pip3 install vosk
pip3 install sounddevice  # For audio recording
pip3 install scipy  # For audio processing

Step 4: Configure Telegram Bot

1. Create Bot with BotFather

1. Open Telegram and search for @BotFather
2. Send /newbot command
3. Follow prompts to name your bot
4. Save the API Token (looks like: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

2. Get Your Telegram ID

1. Search for @userinfobot in Telegram
2. Send any message
3. Copy your User ID (looks like: 123456789)

3. Update .env

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_ALLOWED_USERS=123456789,987654321  # Your ID + friends' IDs

Step 5: Set Up Webhook

Option A: Using ngrok (Quick Testing)

# Install ngrok
npm install -g ngrok

# Start local server
node bin/zcode.js --no-cli &

# Expose to internet (in new terminal)
ngrok http 3001

# Copy the HTTPS URL (e.g., https://abc123.ngrok.io)
# Update .env:
# ZCODE_WEBHOOK_URL=https://abc123.ngrok.io/telegram/webhook

# Set webhook via API
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://abc123.ngrok.io/telegram/webhook"

Option B: Using Domain (Production)

# 1. Set up Nginx reverse proxy
sudo nano /etc/nginx/sites-available/zcode

# Add:
server {
    listen 80;
    server_name your-domain.com;

    location /telegram/webhook {
        proxy_pass http://localhost:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

# Enable site
sudo ln -s /etc/nginx/sites-available/zcode /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

# 2. Get SSL certificate (Let's Encrypt)
sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

# 3. Set webhook
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://your-domain.com/telegram/webhook"

Step 6: Install Systemd Service

1. Copy Service File

cp scripts/zcode.service ~/.config/systemd/user/

2. Edit Service File (if needed)

nano ~/.config/systemd/user/zcode.service

Update paths if necessary:

[Service]
ExecStart=/usr/bin/node /home/uroma2/zcode-cli-x/bin/zcode.js --no-cli
WorkingDirectory=/home/uroma2/zcode-cli-x

3. Enable and Start

systemctl --user daemon-reload
systemctl --user enable zcode
systemctl --user start zcode

4. Verify

systemctl --user status zcode
# Should show: Active: active (running)

journalctl --user -u zcode -f
# Should show: zCode CLI X running 24/7

---

Configuration Reference

Environment Variables

Variable	Required	Description	Example
GLM_BASE_URL	✅	Z.AI API base URL	https://api.z.ai/api/coding/paas/v4
ZAI_API_KEY	✅	Z.AI API key	d88afea988...
TELEGRAM_BOT_TOKEN	✅	Telegram bot token	123456789:ABCdef...
TELEGRAM_ALLOWED_USERS	✅	Comma-separated user IDs	123456789,987654321
ZCODE_WEBHOOK_URL	✅	Webhook endpoint URL	https://your-domain.com/telegram/webhook
VOSK_MODEL_PATH	❌	Path to Vosk model	~/vosk-models/vosk-model-small-0.15
FFMPEG_PATH	❌	Path to ffmpeg binary	/usr/bin/ffmpeg
RTK_PATH	❌	Path to RTK binary	~/.local/bin/rtk
LOG_LEVEL	❌	Logging level	debug, info, warn, error
LOG_FILE	❌	Log file path	logs/zcode.log

Config File (.zcode.config.json)

{
  "api": {
    "baseUrl": "https://api.z.ai/api/coding/paas/v4",
    "models": {
      "default": "glm-5.1",
      "fallback": "glm-4v"
    }
  },
  "telegram": {
    "allowedUsers": ["123456789"],
    "webhookUrl": "https://your-domain.com/telegram/webhook"
  },
  "memory": {
    "maxEntries": 500,
    "evictionPolicy": "lru"
  },
  "agents": {
    "enabled": ["coder", "reviewer", "architect"],
    "maxTurns": 10
  }
}

---

Troubleshooting

Bot Not Starting

Error: EADDRINUSE: address already in use :::3001

# Kill existing process
lsof -ti:3001 | xargs kill -9
systemctl --user restart zcode

Error: Telegram bot token not configured

# Check .env file
cat .env | grep TELEGRAM_BOT_TOKEN
# Should show: TELEGRAM_BOT_TOKEN=123456789:ABCdef...

Voice I/O Not Working

Error: Vosk model not found

# Check model path
ls -la ~/vosk-models/vosk-model-small-0.15/
# Should show: model.json, graphs, etc.

# Update .env
VOSK_MODEL_PATH=/home/uroma2/vosk-models/vosk-model-small-0.15

Error: ffmpeg not found

# Install ffmpeg
sudo apt-get install -y ffmpeg

# Verify
ffmpeg -version

Webhook Not Receiving Messages

Error: Webhook not set

# Manually set webhook
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://your-domain.com/telegram/webhook"

# Check webhook info
curl -X GET "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"

Error: Connection timeout

# Check firewall
sudo ufw status
# Should allow port 80 and 443

# Check Nginx
sudo nginx -t
sudo systemctl status nginx

Service Not Running

Error: Active: inactive (dead)

# Check logs
journalctl --user -u zcode -n 50 --no-pager

# Restart service
systemctl --user restart zcode

# Check status
systemctl --user status zcode

---

Advanced Setup

Docker Deployment (Coming Soon)

# Build image
docker build -t zcode-cli-x .

# Run container
docker run -d \
  --name zcode \
  -v $(pwd)/.env:/app/.env \
  -v $(pwd)/logs:/app/logs \
  -p 3001:3001 \
  zcode-cli-x

Multiple Instances

# Copy service file with different name
cp scripts/zcode.service ~/.config/systemd/user/zcode-2.service

# Edit service file
nano ~/.config/systemd/user/zcode-2.service
# Change: ExecStart=/usr/bin/node /home/uroma2/zcode-cli-x/bin/zcode.js --no-cli
# To: ExecStart=/usr/bin/node /home/uroma2/zcode-cli-x/bin/zcode.js --no-cli --instance 2

# Enable and start
systemctl --user enable zcode-2
systemctl --user start zcode-2

Custom Domain with SSL

# 1. Get domain DNS record
# Add A record: your-domain.com -> YOUR_SERVER_IP

# 2. Install Nginx
sudo apt-get install -y nginx

# 3. Configure Nginx
sudo nano /etc/nginx/sites-available/zcode

server {
    listen 80;
    server_name your-domain.com;

    location /telegram/webhook {
        proxy_pass http://localhost:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

# 4. Enable site
sudo ln -s /etc/nginx/sites-available/zcode /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

# 5. Get SSL certificate
sudo certbot --nginx -d your-domain.com

# 6. Set webhook
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://your-domain.com/telegram/webhook"

---

Verification

Check All Components

# 1. Node.js version
node --version  # Should show v20.x+

# 2. npm version
npm --version   # Should show 9.x+

# 3. ffmpeg
ffmpeg -version  # Should show version info

# 4. Python & Vosk
python3 --version  # Should show 3.8+
python3 -c "import vosk; print(vosk.__version__)"  # Should print version

# 5. Service status
systemctl --user status zcode  # Should show: active (running)

# 6. Webhook info
curl -X GET "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"
# Should show: {"ok":true,"url":"https://your-domain.com/telegram/webhook"}

# 7. Test bot
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getMe"
# Should show your bot info

Run Smoke Tests

# Run Ruflo smoke tests
node test-ruflo-smoke.mjs

# Should show:
# ✅ PluginSystem: 10/10
# ✅ HookSystem: 4/4
# ✅ AgentSystem: 9/9
# ✅ SwarmCoordinator: 12/12
# ✅ AgentOrchestrator: 4/4
# ✅ MemoryBackend: 14/14
# Total: 53/53

---

Next Steps

1. ✅ Test the bot — Send /start in Telegram
2. ✅ Explore features — Try /tools, /agents, /memory
3. ✅ Configure voice — Set up Vosk model and ffmpeg
4. ✅ Customize — Edit .zcode.config.json for your needs
5. ✅ Monitor — Use journalctl --user -u zcode -f to watch logs

---

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: README.md, ARCHITECTURE.md

---

Ready to deploy? Follow the steps above and your bot will be running in minutes! 🚀