> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gensparx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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>

The recommended way to deploy gensparx to production servers is via **[gensparx-ansible](https://github.com/gensparx/gensparx-ansible)** — an automated installer with security-first architecture.

## Quick Start

One-command install:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/gensparx/gensparx-ansible/main/install.sh | bash
```

> **📦 Full guide: [github.com/gensparx/gensparx-ansible](https://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](/gateway/sandboxing) for details.

## Post-Install Setup

After installation completes, switch to the gensparx user:

```bash theme={null}
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

```bash theme={null}
#

<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:

```bash theme={null}
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](/tools/multi-agent-sandbox-tools) for sandbox configuration.

## Manual Installation

If you prefer manual control over the automation:

```bash theme={null}
#

<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](/install/updating) for the standard update flow.

To re-run the Ansible playbook (e.g., for configuration changes):

```bash theme={null}
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

```bash theme={null}
#

<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

```bash theme={null}
#

<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:

```bash theme={null}
sudo -i -u gensparx
gensparx channels login
```

## Advanced Configuration

For detailed security architecture and troubleshooting:

* [Security Architecture](https://github.com/gensparx/gensparx-ansible/blob/main/docs/security.md)
* [Technical Details](https://github.com/gensparx/gensparx-ansible/blob/main/docs/architecture.md)
* [Troubleshooting Guide](https://github.com/gensparx/gensparx-ansible/blob/main/docs/troubleshooting.md)

## Related

* [gensparx-ansible](https://github.com/gensparx/gensparx-ansible) — full deployment guide
* [Docker](/install/docker) — containerized gateway setup
* [Sandboxing](/gateway/sandboxing) — agent sandbox configuration
* [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) — per-agent isolation