Skip to main content

​

This install path is advanced and not part of the primary support path. Use Docker or Podman for a fully supported setup.
The recommended way to deploy gensparx to production servers is via gensparx-ansible — an automated installer with security-first architecture.

​
Quick Start

One-command install: 
curl -fsSL https://raw.githubusercontent.com/gensparx/gensparx-ansible/main/install.sh | bash
📦 Full guide: github.com/gensparx/gensparx-ansible The gensparx-ansible repo is the source of truth for Ansible deployment. This page is a quick overview.

​
What You Get

  • 🔒 Firewall-first security: UFW + Docker isolation (only SSH + Tailscale accessible)
  • 🔐 Tailscale VPN: Secure remote access without exposing services publicly
  • 🐳 Docker: Isolated sandbox containers, localhost-only bindings
  • 🛡️ Defense in depth: 4-layer security architecture
  • 🚀 One-command setup: Complete deployment in minutes
  • 🔧 Systemd integration: Auto-start on boot with hardening

​
Requirements

  • OS: Debian 11+ or Ubuntu 20.04+
  • Access: Root or sudo privileges
  • Network: Internet connection for package installation
  • Ansible: 2.14+ (installed automatically by quick-start script)

​
What Gets Installed

The Ansible playbook installs and configures:
  1. Tailscale (mesh VPN for secure remote access)
  2. UFW firewall (SSH + Tailscale ports only)
  3. Docker CE + Compose V2 (for agent sandboxes)
  4. Node.js 22.x + pnpm (runtime dependencies)
  5. Gensparx (host-based, not containerized)
  6. Systemd service (auto-start with security hardening)
Note: The gateway runs directly on the host (not in Docker), but agent sandboxes use Docker for isolation. See Sandboxing for details.

​
Post-Install Setup

After installation completes, switch to the gensparx user: 
sudo -i -u gensparx
The post-install script will guide you through:
  1. Onboarding wizard: Configure gensparx settings
  2. Provider login: Connect WhatsApp/Telegram/Discord/Signal
  3. Gateway testing: Verify the installation
  4. Tailscale setup: Connect to your VPN mesh

​
Quick commands

# 

<Warning>
This install path is advanced and not part of the primary support path. Use Docker or Podman for a fully supported setup.
</Warning>
sudo systemctl status gensparx

# 

<Warning>
This install path is advanced and not part of the primary support path. Use Docker or Podman for a fully supported setup.
</Warning>
sudo journalctl -u gensparx -f

# 

<Warning>
This install path is advanced and not part of the primary support path. Use Docker or Podman for a fully supported setup.
</Warning>
sudo systemctl restart gensparx

# 

<Warning>
This install path is advanced and not part of the primary support path. Use Docker or Podman for a fully supported setup.
</Warning>
sudo -i -u gensparx
gensparx channels login

​
Security Architecture

​
4-Layer Defense

  1. Firewall (UFW): Only SSH (22) + Tailscale (41641/udp) exposed publicly
  2. VPN (Tailscale): Gateway accessible only via VPN mesh
  3. Docker Isolation: DOCKER-USER iptables chain prevents external port exposure
  4. Systemd Hardening: NoNewPrivileges, PrivateTmp, unprivileged user

​
Verification

Test external attack surface: 
nmap -p- YOUR_SERVER_IP
Should show only port 22 (SSH) open. All other services (gateway, Docker) are locked down.

​
Docker Availability

Docker is installed for agent sandboxes (isolated tool execution), not for running the gateway itself. The gateway binds to localhost only and is accessible via Tailscale VPN. See Multi-Agent Sandbox & Tools for sandbox configuration.

​
Manual Installation

If you prefer manual control over the automation: 
# 

<Warning>
This install path is advanced and not part of the primary support path. Use Docker or Podman for a fully supported setup.
</Warning>
sudo apt update && sudo apt install -y ansible git

# 

<Warning>
This install path is advanced and not part of the primary support path. Use Docker or Podman for a fully supported setup.
</Warning>
git clone https://github.com/gensparx/gensparx-ansible.git
cd gensparx-ansible

# 

<Warning>
This install path is advanced and not part of the primary support path. Use Docker or Podman for a fully supported setup.
</Warning>
ansible-galaxy collection install -r requirements.yml

# 

<Warning>
This install path is advanced and not part of the primary support path. Use Docker or Podman for a fully supported setup.
</Warning>
./run-playbook.sh

# 

<Warning>
This install path is advanced and not part of the primary support path. Use Docker or Podman for a fully supported setup.
</Warning>
# 

<Warning>
This install path is advanced and not part of the primary support path. Use Docker or Podman for a fully supported setup.
</Warning>

​
Updating Gensparx

The Ansible installer sets up gensparx for manual updates. See Updating for the standard update flow. To re-run the Ansible playbook (e.g., for configuration changes): 
cd gensparx-ansible
./run-playbook.sh
Note: This is idempotent and safe to run multiple times.

​
Troubleshooting

​
Firewall blocks my connection

If you’re locked out:
  • Ensure you can access via Tailscale VPN first
  • SSH access (port 22) is always allowed
  • The gateway is only accessible via Tailscale by design

​
Service won’t start

# 

<Warning>
This install path is advanced and not part of the primary support path. Use Docker or Podman for a fully supported setup.
</Warning>
sudo journalctl -u gensparx -n 100

# 

<Warning>
This install path is advanced and not part of the primary support path. Use Docker or Podman for a fully supported setup.
</Warning>
sudo ls -la /opt/gensparx

# 

<Warning>
This install path is advanced and not part of the primary support path. Use Docker or Podman for a fully supported setup.
</Warning>
sudo -i -u gensparx
cd ~/gensparx
pnpm start

​
Docker sandbox issues

# 

<Warning>
This install path is advanced and not part of the primary support path. Use Docker or Podman for a fully supported setup.
</Warning>
sudo systemctl status docker

# 

<Warning>
This install path is advanced and not part of the primary support path. Use Docker or Podman for a fully supported setup.
</Warning>
sudo docker images | grep gensparx-sandbox

# 

<Warning>
This install path is advanced and not part of the primary support path. Use Docker or Podman for a fully supported setup.
</Warning>
cd /opt/gensparx/gensparx
sudo -u gensparx ./scripts/sandbox-setup.sh

​
Provider login fails

Make sure you’re running as the gensparx user: 
sudo -i -u gensparx
gensparx channels login

​
Advanced Configuration

For detailed security architecture and troubleshooting: