What to do if service stops on logout?

Enable lingering: run loginctl enable-linger $USER. This keeps systemd user services running even after SSH disconnect.

What to do if permission denied on credentials?

Credentials should be owned by your user. Run chown -R $USER:$USER ~/.clawdbot to fix permissions.

What are common causes for service not starting?

Common causes include: Node.js not found (check PATH), port already in use, config file syntax error.

What to do if out of memory?

Add memory limits to the systemd service configuration: MemoryLimit=512M.

Moltbot Linux Deployment

Run Moltbot as a systemd service on Linux for reliable, always-on operation.

TL;DR

# Install
git clone https://github.com/moltbot/moltbot.git
cd moltbot && pnpm install

# Setup (creates config and workspace)
pnpm moltbot setup

# Enable lingering (keeps service running after logout)
sudo loginctl enable-linger $USER

# Start
systemctl --user start moltbot
systemctl --user enable moltbot

Prerequisites

Linux (Ubuntu 22.04+, Debian 12+, or similar)
Node.js >= 22
pnpm
systemd (standard on most distros)

Installation

1. Install Node.js

# Using NodeSource (recommended)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install pnpm
npm install -g pnpm

2. Clone and Build

git clone https://github.com/moltbot/moltbot.git
cd moltbot
pnpm install

3. Run Setup

pnpm moltbot setup

This creates:

~/.clawdbot/moltbot.json - Your configuration
~/clawd - Your workspace directory

4. Connect Channels

pnpm moltbot channels login

Follow the prompts to authenticate your messaging platforms.

Systemd User Service

Moltbot installs as a systemd user service by default. This means:

It runs under your user account
Credentials stay in your home directory
Controlled with systemctl --user

Enable Lingering

By default, systemd stops user services when you log out. To keep Moltbot running:

sudo loginctl enable-linger $USER

Critical: Without lingering, Moltbot will stop when you disconnect SSH!

Service Commands

# Start the service
systemctl --user start moltbot

# Stop the service
systemctl --user stop moltbot

# Restart the service
systemctl --user restart moltbot

# Enable auto-start on boot
systemctl --user enable moltbot

# Check status
systemctl --user status moltbot

# View logs
journalctl --user -u moltbot -f

System Service (Multi-User/Server)

For always-on servers or multi-user setups, use a system service instead:

Create System Service File

sudo nano /etc/systemd/system/moltbot.service

[Unit]
Description=Moltbot Gateway
After=network.target

[Service]
Type=simple
User=moltbot
Group=moltbot
WorkingDirectory=/opt/moltbot
ExecStart=/usr/bin/node /opt/moltbot/dist/gateway/index.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Create Service User

sudo useradd -r -s /bin/false moltbot
sudo mkdir -p /opt/moltbot
sudo chown moltbot:moltbot /opt/moltbot

Install and Start

# Copy files
sudo cp -r . /opt/moltbot/
sudo chown -R moltbot:moltbot /opt/moltbot

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable moltbot
sudo systemctl start moltbot

Configuration

Config File Location

User service: ~/.clawdbot/moltbot.json
System service: /opt/moltbot/.clawdbot/moltbot.json or /etc/moltbot/config.json

Example Configuration

{
  "workspace": "~/clawd",
  "gateway": {
    "port": 18789,
    "host": "127.0.0.1"
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "tokenFile": "~/.clawdbot/credentials/telegram-token"
    }
  }
}

File Locations

What	User Service	System Service
Config	`~/.clawdbot/moltbot.json`	`/etc/moltbot/config.json`
Credentials	`~/.clawdbot/credentials/`	`/var/lib/moltbot/credentials/`
Sessions	`~/.clawdbot/agents/`	`/var/lib/moltbot/agents/`
Logs	`/tmp/moltbot/ or journalctl`	`/var/log/moltbot/`
Workspace	`~/clawd`	`/var/lib/moltbot/workspace/`

Firewall Configuration

If using a firewall, allow the Gateway port:

# UFW
sudo ufw allow 18789/tcp

# firewalld
sudo firewall-cmd --add-port=18789/tcp --permanent
sudo firewall-cmd --reload

The Gateway only needs to be accessible locally unless you're running the UI on a different machine.

Health Check

Verify your installation:

pnpm moltbot health

Or create a simple health check script:

#!/bin/bash
curl -s http://127.0.0.1:18789/health || exit 1

Updating

User Service

cd ~/moltbot
git pull
pnpm install
systemctl --user restart moltbot

System Service

cd /opt/moltbot
sudo -u moltbot git pull
sudo -u moltbot pnpm install
sudo systemctl restart moltbot

Common Issues

Service Stops on Logout

sudo loginctl enable-linger $USER

Permission Denied on Credentials

ls -la ~/.clawdbot/
# Should be owned by your user

# Fix if needed:
chown -R $USER:$USER ~/.clawdbot/

Service Won't Start

journalctl --user -u moltbot -n 50

Common causes:

Node.js not found (check PATH)
Port already in use
Config file syntax error

Out of Memory

Add memory limits to the service:

[Service]
MemoryMax=512M

Next Steps

Channel Integration

Connect messaging platforms

View guide

Configuration Reference

All config options

View guide

Security Hardening

Linux security best practices

View guide

Moltbot Linux Deployment

TL;DR

Prerequisites

Installation

1. Install Node.js

2. Clone and Build

3. Run Setup

4. Connect Channels

Systemd User Service

Enable Lingering

Service Commands

System Service (Multi-User/Server)

Create System Service File

Create Service User

Install and Start

Configuration

Config File Location

Example Configuration

File Locations

Firewall Configuration

Health Check

Updating

User Service

System Service

Common Issues

Next Steps

Channel Integration

Configuration Reference

Security Hardening

Related