🦞 clincher

One curl. Hardened AI agent. Done.

Why • Quick Start • Architecture • Deployment Guide • Security • Troubleshooting

Setting up a production AI agent on a VPS is a slog. Firewall rules, egress proxies, socket isolation, sandbox hardening, credential rotation. Miss one and your agent has root-equivalent access to the internet. Nobody wants that.

clincher handles all of it with one Ansible playbook:

• openclaw-net runs internal: true. Your agent can't reach the internet directly.
• Smokescreen proxies egress traffic. Only LLM API domains get through.
• One curl pipes to bash on a fresh Ubuntu 24.04 box and you're done.
• The whole thing is idempotent. Run it again, nothing breaks.
• 9 hardening layers. SSH, containers, sandbox, firewall, the works.

SSH into a fresh Ubuntu 24.04 VPS as root:

curl -fsSL https://raw.githubusercontent.com/droxey/clincher/main/bootstrap.sh | bash

That installs Ansible, clones the repo, asks for your API keys and domain, generates secrets, encrypts the vault, and runs the playbook. Have your Anthropic key, Voyage key, and domain name handy.

Prefer to read before you run?

curl -fsSL https://raw.githubusercontent.com/droxey/clincher/main/bootstrap.sh -o bootstrap.sh
less bootstrap.sh
bash bootstrap.sh

# 1. Clone and configure
git clone https://github.com/droxey/clincher.git && cd clincher
cp group_vars/all/vault.yml.example group_vars/all/vault.yml
$EDITOR group_vars/all/vault.yml          # API keys, Telegram token, 3 internal secrets
ansible-vault encrypt group_vars/all/vault.yml

# 2. Point at your server
$EDITOR inventory/hosts.yml              # set ansible_host to your VPS IP

# 3. Deploy
ansible-playbook playbook.yml -i inventory/hosts.yml --ask-vault-pass

Working on clincher itself? make help lists targets. make check runs the full CI suite locally.

graph TB
    CF["☁️ Cloudflare<br/>WAF + CDN"]
    PROXY["🔒 Caddy / Nginx<br/>reverse proxy"]

    subgraph INTERNAL ["🔐 openclaw-net · internal · no direct internet"]
        GW["🤖 openclaw<br/>gateway + agent runtime"]
        DP["🐳 docker-proxy<br/>socket proxy"]
        LLM["💬 litellm<br/>LLM routing + cost controls"]
        REDIS["🗄️ redis<br/>RediSearch semantic cache"]
        EGRESS["🚪 openclaw-egress<br/>Smokescreen egress whitelist"]
    end

    LLMAPI["☁️ LLM APIs<br/>.anthropic.com · .openai.com"]

    CF -->|HTTPS| PROXY
    PROXY -->|proxy-net| GW
    GW --> DP
    GW --> LLM
    GW --> REDIS
    LLM --> EGRESS
    EGRESS -->|egress-net| LLMAPI

    classDef external fill:#f9f0ff,stroke:#9b59b6,stroke-width:2px,color:#333
    classDef proxy fill:#e8f8f5,stroke:#1abc9c,stroke-width:2px,color:#333
    classDef core fill:#ebf5fb,stroke:#3498db,stroke-width:2px,color:#333

    class CF,LLMAPI external
    class PROXY proxy
    class GW,DP,LLM,REDIS,EGRESS core

Three bridge networks keep things separated. openclaw-net is internal, no internet. egress-net lets the proxy reach LLM APIs and nothing else. proxy-net connects the reverse proxy to the gateway.

Full architecture docs cover images, version pins, and the monitoring topology on the second VPS.

Nine hardening layers: network isolation, egress control, socket proxy, container caps, sandbox isolation, tool denials, file-based secrets, SSH lockdown, UFW + fail2ban.

# Run the built-in security audit
docker exec $(docker ps -q -f "name=openclaw") openclaw security audit --deep

# Check sandbox status
docker exec $(docker ps -q -f "name=openclaw") openclaw sandbox explain

Full security model has the threat model, layer-by-layer breakdown, and verification commands.

CONTRIBUTING.md has the details. Short version: add a role, improve a prompt, or report a security issue.

MIT