ironclaw/docs/drafts/install/vps.mdx

---
title: VPS Installation
sidebarTitle: VPS / Cloud
description: Deploy IronClaw to a cloud server
---

Deploy IronClaw to a remote VPS or cloud server for always-on operation.

## Recommended Providers

- **DigitalOcean**: Droplets from $6/month
- **Hetzner**: CX11 from €4.51/month
- **AWS**: t3.small or larger
- **Google Cloud**: e2-small or larger
- **Azure**: B1s or larger

Minimum specs: 1 vCPU, 2 GB RAM, 20 GB SSD

## Prerequisites

```bash
# SSH into your server
ssh user@your-server-ip

# Update packages
sudo apt update && sudo apt upgrade -y
```

## Step 1: Install IronClaw

```bash
# Install IronClaw
curl -fsSL https://install.ironclaw.ai | bash

# Add to PATH if needed
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
```

## Step 2: Install PostgreSQL

PostgreSQL is recommended for production deployments.

```bash
# Install PostgreSQL
sudo apt install postgresql postgresql-contrib

# Start PostgreSQL
sudo systemctl enable --now postgresql

# Create database and user
sudo -u postgres psql <<EOF
CREATE USER ironclaw WITH PASSWORD 'your-secure-password';
CREATE DATABASE ironclaw OWNER ironclaw;
EOF

# Detect PostgreSQL major version (e.g., 14, 15, 16)
PG_MAJOR=$(psql -V | awk '{print $3}' | cut -d. -f1)
# Install matching pgvector package for the detected PostgreSQL version
sudo apt install "postgresql-$PG_MAJOR-pgvector"
# Enable the vector extension in the ironclaw database
sudo -u postgres psql -d ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"
```

## Step 3: Run the Wizard

<Warning>
**Browser OAuth blocked on VPS.** The default NEAR AI authentication requires a browser on the same machine. On a VPS, use:

1. **NEAR AI Cloud API key** (recommended): Get an API key from https://cloud.near.ai and paste it into the wizard
2. **Custom callback URL**: Set `IRONCLAW_OAUTH_CALLBACK_URL` to a publicly reachable URL

</Warning>

```bash
ironclaw onboard
```

**Wizard selections:**

1. **Database**: Select "PostgreSQL"
   - Enter connection string: `postgres://ironclaw:your-secure-password@localhost/ironclaw`

2. **Security**: Select "OS Keychain" or "Environment Variable"

3. **Inference Provider**: For NEAR AI, select option 4: "NEAR AI Cloud API key"
   - Paste your API key from https://cloud.near.ai

4. **Model Selection**: Choose from the list

5. **Embeddings**: Enable if using OpenAI or NEAR AI

6. **Channels**: Enable Web Gateway and HTTP Webhook

7. **Extensions**: Install desired tools

8. **Heartbeat**: Optional, for periodic tasks

## Step 4: Firewall Configuration

<Warning>
**Important:** IronClaw's orchestrator binds to `0.0.0.0:50051` on Linux for container communication. This port should **not** be exposed externally. The firewall configuration below includes rules to block external access to this port—do not add any UFW allow rules for `50051`.
</Warning>

```bash
# Install UFW if not present
sudo apt install ufw

# Default deny incoming
sudo ufw default deny incoming
sudo ufw default allow outgoing

# Allow SSH
sudo ufw allow 22/tcp

# Allow Web Gateway
sudo ufw allow 3000/tcp

# Allow HTTP Webhook (if using)
sudo ufw allow 8080/tcp

# Orchestrator gRPC port (internal only)
# UFW already denies incoming traffic by default; do NOT add an allow rule for 50051.
# If you run Docker workers on the same host, you can allow only from the Docker bridge, e.g.:
#   sudo ufw allow in on docker0 to any port 50051 proto tcp
#   sudo ufw deny  in on eth0    to any port 50051 proto tcp

# Enable firewall
sudo ufw enable
```

## Step 5: Reverse Proxy (HTTPS)

For external access, use a reverse proxy with TLS:

### Option A: Caddy (Recommended)

```bash
# Install Caddy
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

# Configure Caddy
sudo tee /etc/caddy/Caddyfile <<EOF
webg.example.com {
  reverse_proxy localhost:3000
}
EOF

# Start Caddy
sudo systemctl enable --now caddy
```

### Option B: nginx

```bash
# Install nginx
sudo apt install nginx

# Configure site
sudo tee /etc/nginx/sites-available/ironclaw <<'EOF'
server {
  listen 443 ssl http2;
  server_name webg.example.com;

  ssl_certificate /etc/letsencrypt/live/webg.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/webg.example.com/privkey.pem;

  location / {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

server {
  listen 80;
  server_name webg.example.com;
  return 301 https://$server_name$request_uri;
}
EOF

# Enable site
sudo ln -sf /etc/nginx/sites-available/ironclaw /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo systemctl restart nginx
```

### Option C: Cloudflare Tunnel

```bash
# Install cloudflared
curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared.deb

# Authenticate
cloudflared tunnel login

# Create tunnel
cloudflared tunnel create ironclaw

# Configure
sudo mkdir -p /etc/cloudflared
sudo tee /etc/cloudflared/config.yml <<EOF
tunnel: YOUR-TUNNEL-ID
credentials-file: /root/.cloudflared/YOUR-TUNNEL-ID.json

ingress:
  - hostname: webg.example.com
    service: http://localhost:3000
  - service: http_status:404
EOF

# Install as service
sudo cloudflared service install
sudo systemctl enable --now cloudflared
```

## Step 6: Service Setup

```bash
# Install systemd service
ironclaw service install

# Configure service
sudo systemctl edit ironclaw
```

Add environment variables:

```ini
[Service]
Environment="DATABASE_BACKEND=postgres"
Environment="DATABASE_URL=postgres://ironclaw:your-secure-password@localhost/ironclaw"
Environment="GATEWAY_HOST=127.0.0.1"
```

Start the service:

```bash
sudo systemctl enable --now ironclaw
sudo systemctl status ironclaw
```

## Step 7: Verify

```bash
# Check service status
sudo systemctl status ironclaw

# View logs
sudo journalctl -u ironclaw -f

# Run diagnostics
ironclaw doctor
```

## Security Hardening

### Fail2ban

```bash
sudo apt install fail2ban

# Create filter
sudo tee /etc/fail2ban/filter.d/ironclaw.conf <<'EOF'
[Definition]
failregex = ^.*Unauthorized.*from <HOST>.*$
            ^.*Invalid token.*from <HOST>.*$
ignoreregex =
EOF

# Create jail
sudo tee /etc/fail2ban/jail.d/ironclaw.conf <<EOF
[ironclaw]
enabled = true
port = http,https
filter = ironclaw
logpath = /var/log/ironclaw/web.log
maxretry = 5
bantime = 3600
EOF

sudo systemctl restart fail2ban
```

### Auto-updates

```bash
# Install unattended-upgrades
sudo apt install unattended-upgrades

# Configure
sudo dpkg-reconfigure unattended-upgrades
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Cannot connect to database" icon="database">
    Verify PostgreSQL is running:
    ```bash
    sudo systemctl status postgresql
    sudo -u postgres psql -c "\l"
    ```
  </Accordion>

  <Accordion title="Web Gateway not accessible" icon="globe">
    Check firewall and binding:
    ```bash
    sudo ufw status
    sudo ss -tlnp | grep 3000
    ```
  </Accordion>

  <Accordion title="NEAR AI authentication fails" icon="key">
    On VPS, use NEAR AI Cloud API key instead of browser OAuth:
    ```bash
    export NEARAI_API_KEY=your-api-key
    ironclaw onboard
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="settings" href="/setup/configuration">
    Full environment variable reference
  </Card>
  <Card title="Channels" icon="message-circle" href="/channels">
    Set up Telegram and other channels
  </Card>
</CardGroup>