📦 Installation Guide

This guide provides detailed installation and configuration instructions for the Wegent platform, including system requirements, installation steps, and configuration options.

---

📋 System Requirements

Hardware Requirements

Component	Minimum	Recommended
CPU	2 cores	4 cores or more
Memory	4 GB	8 GB or more
Storage	20 GB	50 GB or more
Network	Stable internet connection	-

Software Requirements

Required Software

• Docker: 20.10+
• Docker Compose: 2.0+
• Git: 2.0+

Optional Software (for development)

• Python: 3.10+
• Node.js: 18+
• MySQL: 8.0+
• Redis: 7+

---

🚀 Installation Methods

Wegent supports two main installation methods:

Method 1: Docker Compose (Recommended)

Suitable for quick deployment and production environments.

Method 2: Source Installation

Suitable for development and custom deployments.

---

📦 Method 1: Docker Compose Installation

Step 1: Clone the Repository

# Clone Wegent repository
git clone https://github.com/wecode-ai/wegent.git

# Enter project directory
cd wegent

Step 2: Configure Environment Variables

# Copy environment template
cp .env.example .env

# Edit .env file
vim .env  # or use another editor

Key Environment Variables

# MySQL Configuration
MYSQL_ROOT_PASSWORD=your_root_password
MYSQL_DATABASE=task_manager
MYSQL_USER=task_user
MYSQL_PASSWORD=your_password

# Redis Configuration
REDIS_PASSWORD=your_redis_password  # Optional
REDIS_PROTOCOL=2  # Default RESP2, compatible with Redis-compatible servers without HELLO support

# Backend Configuration
PASSWORD_KEY=your-password-key-here
DATABASE_URL=mysql+pymysql://task_user:your_password@mysql:3306/task_manager
CHECK_SYSTEM_INITIALIZATION_STATUS=True

# Attachment Storage Configuration (Optional)
# Default: mysql (stores files in database)
# Options: mysql, s3, minio
ATTACHMENT_STORAGE_BACKEND=mysql

# S3/MinIO Configuration (only required when using s3 or minio backend)
# ATTACHMENT_S3_ENDPOINT=https://s3.amazonaws.com  # or http://minio:9000
# ATTACHMENT_S3_ACCESS_KEY=your_access_key
# ATTACHMENT_S3_SECRET_KEY=your_secret_key
# ATTACHMENT_S3_BUCKET=attachments
# ATTACHMENT_S3_REGION=us-east-1
# ATTACHMENT_S3_USE_SSL=true

# Frontend Configuration
# Runtime variables (recommended, can be changed without rebuilding)
# Set via docker-compose.yml environment section
# RUNTIME_INTERNAL_API_URL=http://backend:8000
# RUNTIME_SOCKET_DIRECT_URL=http://backend:8000
# RUNTIME_WEWORK_CODE_URL=https://wework.example.com/coding  # Optional: route coding entry points to Wework
# Legacy (deprecated): NEXT_PUBLIC_API_URL=http://localhost:8000

# Wework frontend build configuration (optional)
# Sets the scaling Wiki link in the cloud device resource note card under Settings -> Connections
# VITE_CLOUD_DEVICE_SCALING_WIKI_URL=https://wiki.example.com/cloud-device-scaling

# Image configuration
# Set to edge when testing CI-published edge images
WEGENT_IMAGE_TAG=latest

# Executor Manager Configuration
# Optional: explicitly override the executor image; leave unset to follow WEGENT_IMAGE_TAG
# EXECUTOR_IMAGE=ghcr.io/wecode-ai/wegent-executor:latest
EXECUTOR_WORKSPACE=/path/to/workspace

When RUNTIME_WEWORK_CODE_URL is empty, Wegent Web opens coding entry points at /chat?agent=code and filters to coding agents. When it is configured, the sidebar shows WeWork instead of Code and opens that runtime URL. This setting is delivered only through /runtime-config; there is no NEXT_PUBLIC_* fallback.

Step 3: Start Services

# Start all services
docker-compose up -d

# Check service status
docker-compose ps

# View logs
docker-compose logs -f

To test CI-published edge images, set the shared image tag:

WEGENT_IMAGE_TAG=edge docker compose up -d

When using install.sh, you can also pass the edge shortcut directly:

curl -fsSL https://raw.githubusercontent.com/wecode-ai/Wegent/main/install.sh | bash -s -- --edge

Step 4: Verify Installation

Wait for services to start completely (about 30 seconds). Database tables and initial data will be created automatically.

Visit the following URLs to verify installation:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/api/docs
• Executor Manager: http://localhost:8001

Step 5: Configure GitHub Integration (Optional)

1. Visit http://localhost:3000
2. Follow on-screen instructions to configure GitHub Personal Access Token
3. Required token permissions:
   • repo - Full repository access
   • workflow - Workflow permissions

---

💻 Method 2: Source Installation

Step 1: Install Required Software

On Ubuntu/Debian

# Update package list
sudo apt-get update

# Install Python
sudo apt-get install python3.10 python3-pip python3-venv

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install MySQL
sudo apt-get install mysql-server

# Install Redis
sudo apt-get install redis-server

# Install Git
sudo apt-get install git

On macOS

# Install using Homebrew
brew install python@3.10 node@18 mysql redis git

Step 2: Setup Database

# Start MySQL
sudo systemctl start mysql  # Linux
# or
brew services start mysql  # macOS

# Login to MySQL
mysql -u root -p

# Create database and user
CREATE DATABASE task_manager;
CREATE USER 'task_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON task_manager.* TO 'task_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Step 3: Setup Redis

# Start Redis
sudo systemctl start redis  # Linux
# or
brew services start redis  # macOS

# Verify Redis
redis-cli ping  # Should return PONG

Step 4: Install Backend

# Enter backend directory
cd backend

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate  # Windows

# Install dependencies
uv sync

# Configure environment variables
cp .env.example .env
vim .env  # Edit configuration

# Create database (tables and initial data will be created automatically on first startup)
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS task_manager CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# Run backend service
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Administrator password: First startup automatically creates the admin administrator account, but it does not assign a default password. By default, CHECK_SYSTEM_INITIALIZATION_STATUS=True makes the backend load the initialization state into memory at startup, and the first visit to the login page forces the administrator password setup flow. Complete that flow before logging in and using the system. Set CHECK_SYSTEM_INITIALIZATION_STATUS=False only for deployments that must skip this check.

Step 5: Install Frontend

In a new terminal:

# Return to the repository root
cd Wegent

# Install pnpm workspace dependencies
pnpm install

# Configure environment variables
cd frontend
cp .env.local.example .env.local
vim .env.local  # Edit configuration

# Run development server
pnpm run dev

Step 6: Install Executor Manager

Local Development

---

⚙️ Advanced Configuration

Custom Ports

Modify docker-compose.yml or environment variables to customize ports:

# docker-compose.yml
services:
  frontend:
    ports:
      - "3001:3000" # Change to 3001
  backend:
    ports:
      - "8001:8000" # Change to 8001

Configure HTTPS

For production environments, use Nginx reverse proxy to configure HTTPS:

# Install Nginx
sudo apt-get install nginx

# Configure reverse proxy
sudo vim /etc/nginx/sites-available/wegent

Example Nginx configuration:

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

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

    location /api {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Data Persistence

Ensure Docker volumes are configured correctly for data persistence:

# docker-compose.yml
volumes:
  mysql_data:
  redis_data:
  workspace_data:

services:
  mysql:
    volumes:
      - mysql_data:/var/lib/mysql

  redis:
    volumes:
      - redis_data:/data

---

🔍 Verify Installation

Check Service Status

# Docker Compose method
docker-compose ps

# Should see all services in Up status

Test API

# Test backend API
curl http://localhost:8000/api/health

# Should return: {"status": "ok"}

Test Frontend

Visit http://localhost:3000 in your browser, you should see the Wegent login page.

---

🐛 Common Issues

Issue 1: Port Already in Use

Error: Error: Port 3000 is already in use

Solution:

# Find process using the port
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or modify port configuration

Issue 2: MySQL Connection Failed

Error: Can't connect to MySQL server

Solution:

# Ensure MySQL is running
docker-compose ps mysql
# or
sudo systemctl status mysql

# Check connection configuration
mysql -u task_user -p -h localhost task_manager

Issue 3: Redis Connection Failed

Error: Error connecting to Redis

Solution:

# Ensure Redis is running
redis-cli ping

# Check Redis configuration
docker-compose logs redis

Issue 4: Docker Image Pull Failed

Error: Error pulling image

Solution:

# Use mirror registry
# Edit /etc/docker/daemon.json
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}

# Restart Docker
sudo systemctl restart docker

---

🔄 Upgrade and Update

Upgrade to Latest Version

# Pull latest code
git pull origin main

# Rebuild images
docker-compose build

# Restart services
docker-compose down
docker-compose up -d

# Update database
docker-compose exec backend python -m alembic upgrade head

---

🗑️ Uninstall

Docker Compose Method

# Stop and remove containers
docker-compose down

# Remove volumes (will delete all data)
docker-compose down -v

# Remove images
docker-compose down --rmi all

Source Installation Method

# Stop all services
# Then delete project directory
rm -rf wegent

# Delete database
mysql -u root -p
DROP DATABASE task_manager;
DROP USER 'task_user'@'localhost';

---

📞 Get Help

If you encounter installation issues:

1. Check Troubleshooting Guide
2. Search GitHub Issues
3. View FAQ
4. Create a new Issue to report problems

---

🔗 Next Steps

After installation, you can:

• Quick Start - Run your first task
• Core Concepts - Learn Wegent's core concepts
• Agent Settings - Configure your first agent
• Development Guide - Setup development environment

---

Installation complete! Start exploring Wegent! 🎉