> ## Documentation Index
> Fetch the complete documentation index at: https://agdiai-597e782f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Ansible

# Ansible Installation

Deploy Agdi to production servers with **[agdi-ansible](https://github.com/agdi/agdi-ansible)** -- an automated installer with security-first architecture.

> [!NOTE]
>
> The [agdi-ansible](https://github.com/agdi/agdi-ansible) repo is the source of truth for Ansible deployment. This page is a quick overview.

## Prerequisites

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

## 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
* **Systemd integration** -- auto-start on boot with hardening
* **One-command setup** -- complete deployment in minutes

## Quick Start

One-command install:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL https://raw.githubusercontent.com/agdi/agdi-ansible/main/install.sh | bash
```

## 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 24 + pnpm** -- runtime dependencies (Node 22 LTS, currently `22.14+`, remains supported)
5. **Agdi** -- 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](https://agdiai-597e782f.mintlify.site/gateway/sandboxing.md) for details.

## Post-Install Setup

**1. Switch to the agdi user**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
sudo -i -u agdi
```

**2. Run the onboarding wizard**

The post-install script guides you through configuring Agdi settings.

**3. Connect messaging providers**

Log in to WhatsApp, Telegram, Discord, or Signal:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi channels login
```

**4. Verify the installation**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
sudo systemctl status agdi
sudo journalctl -u agdi -f
```

**5. Connect to Tailscale**

Join your VPN mesh for secure remote access.

### Quick Commands

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Check service status
sudo systemctl status agdi

# View live logs
sudo journalctl -u agdi -f

# Restart gateway
sudo systemctl restart agdi

# Provider login (run as agdi user)
sudo -i -u agdi
agdi channels login
```

## Security Architecture

The deployment uses a 4-layer defense model:

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

To verify your external attack surface:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
nmap -p- YOUR_SERVER_IP
```

Only port 22 (SSH) should be open. All other services (gateway, Docker) are locked down.

Docker is installed for agent sandboxes (isolated tool execution), not for running the gateway itself. See [Multi-Agent Sandbox and Tools](https://agdiai-597e782f.mintlify.site/tools/multi-agent-sandbox-tools.md) for sandbox configuration.

## Manual Installation

If you prefer manual control over the automation:

**1. Install prerequisites**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
sudo apt update && sudo apt install -y ansible git
```

**2. Clone the repository**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
git clone https://github.com/agdi/agdi-ansible.git
cd agdi-ansible
```

**3. Install Ansible collections**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
ansible-galaxy collection install -r requirements.yml
```

**4. Run the playbook**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
./run-playbook.sh
```

Alternatively, run directly and then manually execute the setup script afterward:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
ansible-playbook playbook.yml --ask-become-pass
# Then run: /tmp/agdi-setup.sh
```

## Updating

The Ansible installer sets up Agdi for manual updates. See [Updating](https://agdiai-597e782f.mintlify.site/install/updating.md) for the standard update flow.

To re-run the Ansible playbook (for example, for configuration changes):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
cd agdi-ansible
./run-playbook.sh
```

This is idempotent and safe to run multiple times.

## Troubleshooting

> [accordion] Firewall blocks my connection
>
> * Ensure you can access via Tailscale VPN first
> * SSH access (port 22) is always allowed
> * The gateway is only accessible via Tailscale by design

> [accordion] Service will not start
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> # Check logs
> sudo journalctl -u agdi -n 100
>
> # Verify permissions
> sudo ls -la /opt/agdi
>
> # Test manual start
> sudo -i -u agdi
> cd ~/agdi
> agdi gateway run
> ```

> [accordion] Docker sandbox issues
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> # Verify Docker is running
> sudo systemctl status docker
>
> # Check sandbox image
> sudo docker images | grep agdi-sandbox
>
> # Build sandbox image if missing
> cd /opt/agdi/agdi
> sudo -u agdi ./scripts/sandbox-setup.sh
> ```

> [accordion] Provider login fails
>
> Make sure you are running as the `agdi` user:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> sudo -i -u agdi
> agdi channels login
> ```

## Advanced Configuration

For detailed security architecture and troubleshooting, see the agdi-ansible repo:

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

## Related

* [agdi-ansible](https://github.com/agdi/agdi-ansible) -- full deployment guide
* [Docker](https://agdiai-597e782f.mintlify.site/install/docker.md) -- containerized gateway setup
* [Sandboxing](https://agdiai-597e782f.mintlify.site/gateway/sandboxing.md) -- agent sandbox configuration
* [Multi-Agent Sandbox and Tools](https://agdiai-597e782f.mintlify.site/tools/multi-agent-sandbox-tools.md) -- per-agent isolation


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.