P-BOX OS is a lightweight, pre-configured operating system image designed for network proxy and routing management. Built on Debian 12 (Bookworm), it provides an intuitive web-based control panel for managing proxy services including mihomo (Clash.Meta) and sing-box.

curl -fsSL https://raw.githubusercontent.com/p-box2025/P-BOX-OS/main/install.sh | bash

Download from Releases:

After downloading, use the smart deployment script:

# Linux/macOS
chmod +x deploy-vm.sh
./deploy-vm.sh

# Windows
# Double-click deploy-vm.bat

⚠️ Security Notice: Please change the default password after first login!

After the VM boots:

1. Get IP Address - The system automatically obtains an IP via DHCP
2. SSH Login - ssh root@<device-ip> (password: pbox123)
3. Terminal Menu - Type pbox to open the interactive management menu
4. Web Panel - Open https://<device-ip> in your browser

# Linux/macOS
gunzip -c pbox-os-amd64-*.img.gz | sudo dd of=/dev/sdX bs=4M status=progress

# Windows: Use balenaEtcher, Rufus, or Win32DiskImager

# Decompress
gunzip pbox-os-amd64-*.img.gz

# Create VM and import disk
qm create 100 --name pbox --memory 2048 --cores 4 --net0 virtio,bridge=vmbr0
qm importdisk 100 pbox-os-amd64-*.img local-lvm --format raw
qm set 100 --scsi0 local-lvm:vm-100-disk-0 --boot order=scsi0
qm start 100

# Convert to VMDK
gunzip pbox-os-amd64-*.img.gz
qemu-img convert -f raw -O vmdk pbox-os-amd64-*.img pbox.vmdk

# Upload to ESXi datastore and create VM via web UI

# Convert to VDI
gunzip pbox-os-amd64-*.img.gz
VBoxManage convertfromraw pbox-os-amd64-*.img pbox.vdi --format VDI

# Create VM in VirtualBox using the VDI file

# Convert to VHDX (requires qemu-img)
qemu-img convert -f raw -O vhdx pbox-os-amd64-*.img pbox.vhdx

# Create VM
New-VM -Name "pbox" -MemoryStartupBytes 2GB -Generation 1 -VHDPath "pbox.vhdx"
Set-VMProcessor -VMName "pbox" -Count 4
Start-VM -Name "pbox"

1. Download the appropriate .img.gz for your device
2. Use Raspberry Pi Imager or balenaEtcher
3. Write to SD card (16GB+ recommended)
4. Insert SD card and power on
5. Connect via Ethernet

• 🌐 Web Control Panel - Modern, responsive web UI
• 🚀 Multi-Core Support - mihomo (Clash.Meta) and sing-box
• 🔄 Subscription Management - Auto-update proxy subscriptions
• 📊 Traffic Monitoring - Real-time connection statistics
• 🌍 GeoIP & Rules - Built-in GeoIP database and rule sets
• 🔒 Secure by Default - Pre-configured firewall and SSL
• ⚡ BBR Enabled - TCP BBR congestion control
• 🔧 Easy Deployment - One-click deployment scripts

/opt/pbox/
├── bin/           # Proxy core binaries
├── configs/       # Configuration files
├── data/          # Runtime data and logs
├── geoip/         # GeoIP databases
├── rulesets/      # Proxy rule sets
└── web/           # Web panel files

# Check services
systemctl status pbox
systemctl status nginx

# Restart services
systemctl restart pbox nginx

# Check network
ip addr
ip route

# Restart networking
systemctl restart networking

# View P-BOX logs
journalctl -u pbox -f

# View system logs
dmesg | tail -50

This project is licensed under the MIT License.

• GitHub: https://github.com/p-box2025/P-BOX-OS
• Releases: https://github.com/p-box2025/P-BOX-OS/releases

Made with ❤️ by P-BOX Team