From ab3154c8f09b553026e2a35899b99db279d78e5a Mon Sep 17 00:00:00 2001
From: elliotsecops <elliotsecops@protonmail.com>
Date: Wed, 28 Jan 2026 12:21:06 -0400
Subject: [PATCH] feat(deploy): add systemd templates for production linux
 deployment

Adds production-ready systemd service templates for Linux deployments.

Includes:
- : Auto-restart configuration for the main process.
- : Configuration for Cloudflare Tunnel dependent on the gateway.
- Documentation in .

This simplifies self-hosting setup on VPS and Home Lab environments.
---
 .../systemd/clawdbot-gateway.service.example  | 21 ++++++
 .../systemd/clawdbot-tunnel.service.example   | 24 +++++++
 docs/deploy/linux-systemd.md                  | 65 +++++++++++++++++++
 3 files changed, 110 insertions(+)
 create mode 100644 deploy/systemd/clawdbot-gateway.service.example
 create mode 100644 deploy/systemd/clawdbot-tunnel.service.example
 create mode 100644 docs/deploy/linux-systemd.md

diff --git a/deploy/systemd/clawdbot-gateway.service.example b/deploy/systemd/clawdbot-gateway.service.example
new file mode 100644
index 000000000..392020766
--- /dev/null
+++ b/deploy/systemd/clawdbot-gateway.service.example
@@ -0,0 +1,21 @@
+[Unit]
+Description=Clawdbot Gateway
+After=network.target
+
+[Service]
+# Replace <YOUR_USER> with your linux username (e.g. ubuntu, pi, etc)
+User=<YOUR_USER>
+# Replace <PATH_TO_CLAWDBOT> with the absolute path to the repo (e.g. /home/user/clawdbot)
+WorkingDirectory=<PATH_TO_CLAWDBOT>
+
+# Adjust node path if necessary (run 'which node' to find yours)
+# You can change the port or auth settings here
+ExecStart=/usr/bin/node dist/entry.js gateway --port 18789 --auth token --token <YOUR_SECURE_TOKEN>
+
+# Restart configuration
+Restart=always
+RestartSec=3
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=multi-user.target
diff --git a/deploy/systemd/clawdbot-tunnel.service.example b/deploy/systemd/clawdbot-tunnel.service.example
new file mode 100644
index 000000000..e64c0a2ff
--- /dev/null
+++ b/deploy/systemd/clawdbot-tunnel.service.example
@@ -0,0 +1,24 @@
+[Unit]
+Description=Cloudflare Tunnel for Clawdbot
+# Ensure the tunnel only starts after the gateway is up
+After=network-online.target clawdbot-gateway.service
+Wants=network-online.target clawdbot-gateway.service
+
+[Service]
+# Replace <YOUR_USER> with your linux username
+User=<YOUR_USER>
+Group=<YOUR_USER>
+Type=notify
+
+# Replace <PATH_TO_CLOUDFLARED> with your cloudflared binary path (usually /usr/local/bin/cloudflared or /usr/bin/cloudflared)
+# Replace <TUNNEL_NAME> with your created tunnel name/UUID
+ExecStart=<PATH_TO_CLOUDFLARED> tunnel run <TUNNEL_NAME>
+
+Restart=always
+RestartSec=5s
+
+# Optional: Point to specific credentials if not in default ~/.cloudflared/ location
+# Environment=TUNNEL_ORIGIN_CERT=/home/<YOUR_USER>/.cloudflared/cert.pem
+
+[Install]
+WantedBy=multi-user.target
diff --git a/docs/deploy/linux-systemd.md b/docs/deploy/linux-systemd.md
new file mode 100644
index 000000000..37241b4a3
--- /dev/null
+++ b/docs/deploy/linux-systemd.md
@@ -0,0 +1,65 @@
+# Linux Systemd Deployment
+
+For production deployments on Linux (VPS, Raspberry Pi, Home Lab), it is recommended to run Clawdbot as a systemd service. This ensures the gateway restarts automatically on crash or reboot.
+
+If you also use Cloudflare Tunnels for remote access, you can configure a dependent service to ensure the tunnel stays connected to the gateway.
+
+## Prerequisites
+
+1.  Node.js (v22+)
+2.  `cloudflared` (if using remote access)
+3.  Clawdbot repository cloned and built (`pnpm install && pnpm build`)
+
+## 1. Setup Gateway Service
+
+1.  Copy the example template:
+    ```bash
+    sudo cp deploy/systemd/clawdbot-gateway.service.example /etc/systemd/system/clawdbot-gateway.service
+    ```
+
+2.  Edit the file to match your user and paths:
+    ```bash
+    sudo nano /etc/systemd/system/clawdbot-gateway.service
+    ```
+    - Change `User=<YOUR_USER>` to your username.
+    - Change `WorkingDirectory` to your Clawdbot folder.
+    - Update `ExecStart` with your preferred flags (e.g. secure token).
+
+3.  Reload and start:
+    ```bash
+    sudo systemctl daemon-reload
+    sudo systemctl enable --now clawdbot-gateway
+    ```
+
+## 2. Setup Cloudflare Tunnel (Optional)
+
+This service is configured to depend on `clawdbot-gateway`, ensuring robust connectivity.
+
+1.  Copy the example template:
+    ```bash
+    sudo cp deploy/systemd/clawdbot-tunnel.service.example /etc/systemd/system/clawdbot-tunnel.service
+    ```
+
+2.  Edit the file:
+    ```bash
+    sudo nano /etc/systemd/system/clawdbot-tunnel.service
+    ```
+    - Update `User` and `ExecStart` paths.
+    - Ensure your tunnel is already created (`cloudflared tunnel create <name>`).
+
+3.  Enable:
+    ```bash
+    sudo systemctl enable --now clawdbot-tunnel
+    ```
+
+## Operations
+
+Check status:
+```bash
+systemctl status clawdbot-gateway clawdbot-tunnel
+```
+
+View logs:
+```bash
+journalctl -u clawdbot-gateway -f
+```