openclaw nix — Securely deploy OpenClaw with a fully…

Pitch

Description

Comments

About this project

Openclaw-nix provides a robust NixOS module designed for the secure deployment of the popular OpenClaw agent infrastructure. With just two lines of configuration, this fully hardened setup addresses common security pitfalls, ensuring a more secure implementation that minimizes the risk of exposure and misconfiguration.

openclaw-nix is a robust NixOS module designed for securely deploying OpenClaw, an industry-leading agent infrastructure platform boasting over 180,000 GitHub stars. Despite its popularity, many OpenClaw installations suffer from critical security misconfigurations, including over 15,200 exposed admin panels on the public internet and an alarming lack of default security measures.

The Challenge

The configuration pitfalls of OpenClaw can lead to significant vulnerabilities:

Public Exposure: Default configurations expose control panels to the internet without proper authentication.
Security Risks: Unrestricted tool execution can allow for unauthorized shell access.
Lack of Protections: Many installations do not enforce TLS or firewall rules, putting user data at risk.

The Solution

openclaw-nix addresses these security challenges with just two simple lines in the NixOS configuration:

services.openclaw.enable = true;
services.openclaw.domain = "agents.example.com";

By enabling this module, users benefit from:

Security Layer	Functionality Description
Gateway Authentication	Auto-generated token required for all connections.
Localhost Binding	The gateway does not directly interact with the internet.
Caddy Reverse Proxy	Provides automatic TLS through Let's Encrypt, along with enhanced security headers.
Tool Allowlisting	Ensures only approved tools are enabled, preventing full mode access.
Systemd Hardening	Enforces strict operating conditions, enhancing security with features like `NoNewPrivileges`.
Firewall Configuration	Limits the open ports to only those necessary for secure operations (443 for HTTPS, 22 for SSH).
Fail2ban Integration	Protects against brute-force SSH attacks.
Dedicated User	Runs OpenClaw as a non-privileged user, enhancing system security.

Quick Setup Options

Two methods simplify the deployment process:

Interactive Setup using the command:
```
nix run github:Scout-DJ/openclaw-nix#quick-setup
```
This script guides users through configuring their domain and API keys while generating a deployable NixOS configuration.

Manual Setup for advanced users:

Add to flake inputs:

inputs = {
  nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  openclaw.url = "github:Scout-DJ/openclaw-nix";
};

Configure as follows:

# configuration.nix
{ config, pkgs, ... }:
{
  services.openclaw = {
    enable = true;
    domain = "agents.example.com";
    modelProvider = "anthropic";
    modelApiKeyFile = "/run/secrets/anthropic-api-key";
    telegram = {
      enable = true;
      tokenFile = "/run/secrets/telegram-bot-token";
    };
  };
}

Deploy the configuration:

sudo nixos-rebuild switch --flake .#myhost

Retrieve the generated authentication token:
```
sudo cat /var/lib/openclaw/auth-token
```

Module Options Overview

Option	Type	Default	Description
`enable`	bool	`false`	Activate OpenClaw deployment.
`domain`	string	`""`	Public domain for Caddy + TLS support.
`gatewayPort`	port	`3000`	Specifies the local gateway port.
`authTokenFile`	path	`/var/lib/openclaw/auth-token`	Path to the auto-generated auth token file.
`toolSecurity`	enum	`"allowlist"`	Defines permit access policies for tools.
`telegram.enable`	bool	`false`	Enables Telegram plugin.
`discord.enable`	bool	`false`	Enables Discord plugin.
`autoUpdate.enable`	bool	`false`	Enables automatic updates.

Strong Security Foundation

The service implements robust systemd hardening features to enhance security:

NoNewPrivileges=yes        # Prevents privilege escalation.
PrivateTmp=yes             # Isolates temporary files.
ProtectSystem=strict       # Enforces read-only filesystem policies.
ProtectHome=yes            # Restricts access to user home directories.

With NixOS, the project benefits from a declarative configuration that is auditable and reproducible, ensuring that deployments remain consistently secure and reliable.

Production-Level Considerations

For environments that require secure management of secrets, consider utilizing:

agenix for age-encrypted secrets.
sops-nix for SOPS integration.

openclaw-nix serves as a critical tool for deploying OpenClaw securely, ensuring that users can utilize its capabilities without compromising on safety.