GitHub - wolfsoftwaresystemsltd/WolfScale: Free tools for building robust, clustered server infrastructure — WolfStack, WolfScale, WolfDisk, WolfNet

🐺 Wolf — Server Clustering Tools Made Simple

Wolf started as a database replication tool and has grown into a suite of server clustering utilities. Every tool runs as a single Rust binary, uses auto-discovery, and is designed to be simple to set up.

WolfScale — Database Replication

Database replication, clustering, and load balancing — the easy way

WolfScale is a lightweight, high-availability replication layer for MariaDB/MySQL. It provides automatic leader election with deterministic failover, WAL-based replication for strong consistency, and a MySQL-compatible proxy for transparent routing—all in a single Rust binary.

Works with MySQL, Percona, and Amazon RDS • MariaDB recommended

Why WolfScale?

Fastest Replication in the Industry

Quick Start

All cluster nodes MUST have identical data before starting WolfScale. WolfScale replicates new changes only — it does NOT sync existing data between nodes.

# Install WolfScale on each server
curl -sSL https://raw.githubusercontent.com/wolfsoftwaresystemsltd/WolfScale/main/setup.sh | bash

Load Balancer

Install the load balancer directly on any server that needs database access. It auto-discovers your cluster — no configuration needed.

curl -sSL https://raw.githubusercontent.com/wolfsoftwaresystemsltd/WolfScale/main/setup_lb.sh | bash

Web Server 1 ─── WolfScale LB ───┐
             (auto-discovers)    │
                                 │
Web Server 2 ─── WolfScale LB ───┼──► WolfScale DB Cluster
             (auto-discovers)    │
                                 │
Web Server 3 ─── WolfScale LB ───┘
             (auto-discovers)

Cluster Commands

wolfctl list servers     # Check cluster status
wolfctl stats            # Live throughput monitoring
wolfctl migrate --from 10.0.10.111:8080   # Migrate data to new node
wolfctl reset --force    # Reset WAL and state (DESTRUCTIVE)

WolfDisk — Distributed Filesystem

Disk sharing and replication across networks — the easy way

WolfDisk is a FUSE-based distributed filesystem that shares and replicates files across Linux servers. Mount a shared directory on any number of machines and have your data automatically synchronised. Supports leader, follower, and client modes.

Why WolfDisk?

Quick Start

# Interactive installer - prompts for node ID, role, and discovery
curl -sSL https://raw.githubusercontent.com/wolfsoftwaresystemsltd/WolfScale/main/wolfdisk/setup.sh | bash

Node Roles

See wolfdisk/README.md for full documentation.

WolfNet — Private Networking

WolfNet creates a secure, encrypted private network between your machines over the internet. Machines on WolfNet can see each other as if they were on the same LAN, but all traffic is encrypted with modern cryptography (X25519 + ChaCha20-Poly1305 — the same crypto as WireGuard).

Why WolfNet?

Quick Start

# Interactive installer — downloads binary, generates keys, creates systemd service
curl -sSL https://raw.githubusercontent.com/wolfsoftwaresystemsltd/WolfScale/main/wolfnet/setup.sh | sudo bash

The installer will:

• Check for /dev/net/tun (with Proxmox/LXC guidance if missing)
• Download and install wolfnet and wolfnetctl
• Generate an X25519 keypair
• Prompt for WolfNet IP address, port, and gateway mode
• Create a systemd service for automatic startup

Easy Peer Setup (Invite/Join)

Connect two machines in seconds — no manual key exchange:

# On the first machine (the one with a public IP / port forwarding):
sudo wolfnet invite

# Output:  sudo wolfnet --config /etc/wolfnet/config.toml join eyJwa...

# Copy that command and run it on the second machine:
sudo wolfnet --config /etc/wolfnet/config.toml join eyJwa...

# It will output a reverse token — run that on the first machine:
sudo wolfnet --config /etc/wolfnet/config.toml join eyJlc...

# Restart WolfNet on both:
sudo systemctl restart wolfnet

The invite token auto-detects the node's public IP, includes the public key, and assigns WolfNet IPs automatically.

NAT Traversal (Relay Forwarding)

WolfNet supports relay forwarding so machines behind NAT firewalls can communicate without port forwarding:

Laptop (behind NAT)          Server (public IP)           Home PC (behind NAT)
    10.0.10.1                   10.0.10.2                   10.0.10.3
        │                           │                           │
        └───── encrypted UDP ──────►│◄────── encrypted UDP ─────┘
                                    │
                             Relay forwards
                            packets between
                           Laptop ◄──► Home PC

How it works:

1. Both the laptop and home PC connect to the server (which has a public IP)
2. When the laptop sends a packet to the home PC, the server detects it's not the destination
3. The server decrypts, re-encrypts for the home PC, and forwards it
4. This happens automatically — no configuration needed
5. Any node that can be reached by both parties can act as a relay

Peer Discovery Methods

WolfNet supports three ways to find and connect to peers — mix and match as needed:

Hostnames are resolved on startup and re-resolved every 60 seconds, so DynDNS changes are picked up automatically. Works with any DNS provider — DynDNS, No-IP, Cloudflare, DuckDNS, or your own domain.

Multi-Server Deployment (Static IPs)

Link multiple standalone servers across different locations into a single WolfNet mesh:

Server A (London)              Server B (New York)           Server C (Tokyo)
  Public: 203.0.113.5            Public: 198.51.100.10         Public: 192.0.2.50
  WolfNet: 10.0.10.1             WolfNet: 10.0.10.2            WolfNet: 10.0.10.3
       │                              │                             │
       └────── encrypted UDP ────────►│◄───── encrypted UDP ────────┘

1. Install WolfNet on each server, giving each a unique WolfNet IP
2. Use sudo wolfnet invite on one server to generate invite tokens
3. Run the invite command on each other server to exchange keys
4. Restart WolfNet — PEX automatically propagates the full mesh topology

💡 You don't need a full mesh in the config. Each server only needs to know about at least one other server. PEX shares the rest automatically within 30 seconds.

Architecture

Machine A (10.0.10.1)          Machine B (10.0.10.2)
┌─────────────────┐            ┌─────────────────┐
│  wolfnet0 (TUN) │◄──────────►│  wolfnet0 (TUN) │
│  10.0.10.1/24   │  Encrypted │  10.0.10.2/24   │
│  ChaCha20-Poly  │  UDP/9600  │  ChaCha20-Poly  │
└─────────────────┘            └─────────────────┘
         ▲                              ▲
         │       Encrypted UDP          │
         └──────────┬───────────────────┘
                    │
           ┌────────▼────────┐
           │  Machine C      │
           │  (Gateway)      │
           │  10.0.10.3/24   │
           │  NAT → Internet │
           └─────────────────┘

CLI Reference

# Daemon
wolfnet                          # Start the daemon (usually via systemd)
wolfnet init --address 10.0.10.1 # Generate config and keypair
wolfnet genkey                   # Generate a new X25519 keypair
wolfnet pubkey                   # Show this node's public key
wolfnet token                    # Show join token for sharing
wolfnet invite                   # Generate invite token for a new peer
wolfnet join <token>             # Join a network using an invite token

# Control utility
wolfnetctl status                # Show node status, IP, uptime
wolfnetctl peers                 # List peers with connection status
wolfnetctl info                  # Combined status and peer list

# Service management
sudo systemctl start wolfnet     # Start service
sudo systemctl status wolfnet    # Check status
sudo journalctl -u wolfnet -f    # View logs

Configuration Example

[network]
address = "10.0.10.1"
listen_port = 9600
discovery = true        # LAN auto-discovery (default)

# Static IP peer
[[peers]]
public_key = "BASE64_PUBLIC_KEY"
endpoint = "203.0.113.5:9600"
allowed_ip = "10.0.10.2"
name = "london-vps"

# DynDNS hostname peer (re-resolved every 60s)
[[peers]]
public_key = "ANOTHER_PUBLIC_KEY"
endpoint = "myhome.dyndns.org:9600"
allowed_ip = "10.0.10.3"
name = "home-server"

Security

⚠️ Proxmox/LXC Users: The TUN device (/dev/net/tun) is blocked by default in LXC containers. See wolfscale.org/wolfnet.html for setup instructions.

Architecture (WolfScale)

Write Flow: Client → Any Node → Forwarded to Leader → Replicated to All Nodes

Read Flow: Client → Any Node → Local Data (or forwarded to Leader if node is behind)

Cluster Sizing

Geo-Distribution: Nodes can be deployed across different data centres or regions. Connect to your nearest node for low-latency reads — if the data isn't up-to-date, the request is automatically forwarded to the leader.

Note: WolfScale doesn't use quorum — only one node needs to survive. While the cluster can run on a single remaining node, it's recommended to maintain at least 2 active nodes for redundancy.

Documentation

• Website: wolfscale.org
• Full Docs: docs/DOCUMENTATION.md
• WolfDisk Docs: wolfdisk/README.md
• WolfNet Docs: wolfscale.org/wolfnet.html
• MariaDB/MySQL Editor: wolfscale.org/wolfstack-mysql.html

Support

• ❤️ Sponsor: Support development
• 💬 Discord: Join our community
• 🔥 Reddit: r/WolfStack
• 🌐 Website: wolf.uk.com
• ⭐ GitHub: Star this repo
• 🐛 Issues: Report a bug

License

MIT License — Free to use, modify, and distribute without restriction.

© 2024-2026 Wolf Software Systems Ltd

⚠️ Disclaimer

USE AT YOUR OWN RISK. This software is provided "as is" without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. In no event shall Wolf Software Systems Ltd be liable for any claim, damages, or other liability arising from the use of this software.

By using Wolf tools, you acknowledge that you are solely responsible for your data and any consequences of using this software.

We hand code and use AI to assist with the development of this software.