Installation

This guide walks you through installing LordClaw on your machine, setting up the database, and configuring remote access.

Prerequisites

Before you start, make sure you have:

Requirement	Minimum Version	Check
Node.js	v18+	`node --version`
npm	v9+	`npm --version`
Docker	Latest	`docker --version`
Git	Any recent	`git --version`
OpenClaw	Running instance	Gateway accessible at `ws://localhost:18789`

LordClaw is the dashboard for OpenClaw. You need a running OpenClaw installation with at least one agent configured before LordClaw becomes useful.

Agent install prompt

If you want an OpenClaw agent to install LordClaw for you, give it this prompt on the machine where OpenClaw runs:

Install LordClaw on this machine.

Requirements:
- Keep LordClaw private. Do not expose it to the public internet.
- Clone https://github.com/InternetJohnny/lordclaw.git into ~/.openclaw/repos/lordclaw.
- Use the repo's Docker Compose file for PostgreSQL.
- Connect LordClaw to the local OpenClaw gateway at ws://localhost:18789 unless this machine uses a different gateway URL.
- Use Tailscale for remote phone or laptop access if remote access is needed.

Steps:
1. Make sure Git, Node.js, npm, and Docker are installed.
2. Run npm install inside ~/.openclaw/repos/lordclaw.
3. Copy .env.example to .env if .env does not exist.
4. Set DATABASE_URL to the value from .env.example unless the user gives a different database.
5. Set GATEWAY_WS_URL to the OpenClaw gateway URL.
6. Set GATEWAY_TOKEN to the local OpenClaw gateway token without printing the token in your final answer.
7. Start PostgreSQL with docker compose up -d.
8. Run npx prisma migrate dev.
9. Start LordClaw on 0.0.0.0:3333.
10. Verify the dashboard opens and connects to OpenClaw.

After installing, report:
- the local LordClaw URL
- whether PostgreSQL is running
- whether Prisma migrations succeeded
- whether LordClaw connects to the OpenClaw gateway
- any remaining Tailscale or firewall step needed for remote access

Install LordClaw

Download the source

Clone the repository from GitHub:

git clone https://github.com/InternetJohnny/lordclaw.git
cd lordclaw

💡

Once releases are available, you’ll also be able to download a specific version from the Releases page.

Install dependencies

npm install

Configure environment

Copy the example environment file and adjust if needed:

cp .env.example .env

The defaults work for a standard local setup:

DATABASE_URL="postgresql://LordClaw_user:LordClaw_password@localhost:5555/LordClaw"
GATEWAY_WS_URL="ws://localhost:18789"
GATEWAY_TOKEN="your-gateway-token-here"

If your gateway uses authentication, replace your-gateway-token-here with your actual token.

Set Up the Database

LordClaw uses PostgreSQL to store usage data, chat history, and preferences. It runs in a Docker container so you don’t need to install Postgres directly.

Start Docker

Make sure Docker Desktop is running:

# macOS
open -a Docker

Wait about 15 seconds for the Docker daemon to fully start.

Start the database container

docker compose up -d

This creates a PostgreSQL 16 container named LordClaw-db on port 5555.

Setting	Value
Container name	`LordClaw-db`
Image	`postgres:16-alpine`
Port	`5555` (host) → `5432` (container)
Database	`LordClaw`
User	`LordClaw_user`
Password	`LordClaw_password`

Port 5555 is used instead of the default 5432 to avoid conflicts with other PostgreSQL installations.

Verify the database is running

docker exec LordClaw-db pg_isready -U LordClaw_user -d LordClaw

You should see: accepting connections.

Run database migrations

npx prisma migrate dev

This creates all the necessary tables for usage tracking, chat persistence, and preferences.

Start LordClaw

npm run dev -- --hostname 127.0.0.1 --port 3334

Then open http://localhost:3334 in your browser.

⚠️

On the Mac Mini, public port 3333 is reserved by the LordClaw proxy. Run the app server on 127.0.0.1:3334.

For remote private-network access, put a proxy or Tailscale Serve route in front of the app instead of binding the dev server directly to the public port.

Production build

For a production deployment instead of a dev server:

npm run build
npm start -- --hostname 127.0.0.1 --port 3334

Surviving Reboots

After a machine restart, Docker, the database container, and LordClaw need to come back up automatically. Here’s how to configure that.

On macOS:

Open Docker Desktop
Go to Settings → General
Enable “Start Docker Desktop when you sign in”

On Linux (systemd):

sudo systemctl enable docker

2. Database container: restart automatically

Configure the LordClaw-db container to start whenever Docker starts:

docker update --restart unless-stopped LordClaw-db

This tells Docker to automatically start the container on daemon startup, unless you explicitly stopped it.

You can verify the restart policy is set:

docker inspect LordClaw-db --format '{{.HostConfig.RestartPolicy.Name}}'
# Should output: unless-stopped

3. LordClaw: auto-start on boot

To have LordClaw itself start automatically, create a Launch Agent (macOS) or systemd service (Linux).

macOS (Launch Agent)

Create ~/Library/LaunchAgents/com.lordclaw.server.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.lordclaw.server</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/node</string>
    <string>node_modules/.bin/next</string>
    <string>start</string>
    <string>-H</string>
    <string>0.0.0.0</string>
    <string>-p</string>
    <string>3333</string>
  </array>
  <key>WorkingDirectory</key>
  <string>/path/to/lordclaw</string>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/lordclaw.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/lordclaw.err</string>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>/usr/local/bin:/usr/bin:/bin</string>
    <key>NODE_ENV</key>
    <string>production</string>
  </dict>
</dict>
</plist>

⚠️

Replace /path/to/lordclaw with the actual path to your LordClaw directory, for example /Users/you/.openclaw/repos/lordclaw. Also update the Node.js path. Run which node to find yours.

Load it:

launchctl load ~/Library/LaunchAgents/com.lordclaw.server.plist

To stop it:

launchctl unload ~/Library/LaunchAgents/com.lordclaw.server.plist

Linux (systemd)

Create /etc/systemd/system/lordclaw.service:

[Unit]
Description=LordClaw Dashboard
After=network.target docker.service
Requires=docker.service
 
[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/lordclaw
ExecStart=/usr/bin/node node_modules/.bin/next start -H 0.0.0.0 -p 3333
Restart=on-failure
RestartSec=10
Environment=NODE_ENV=production
 
[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable lordclaw
sudo systemctl start lordclaw

Check status:

sudo systemctl status lordclaw

Verify Everything Works

After a fresh boot, run through this checklist:

# 1. Docker is running
docker info > /dev/null 2>&1 && echo "✅ Docker" || echo "❌ Docker"
 
# 2. Database container is healthy
docker inspect -f '{{.State.Health.Status}}' LordClaw-db 2>/dev/null
 
# 3. Database accepts connections
docker exec LordClaw-db pg_isready -U LordClaw_user -d LordClaw
 
# 4. LordClaw is serving
curl -s http://localhost:3333 > /dev/null && echo "✅ LordClaw" || echo "❌ LordClaw"
 
# 5. Gateway is reachable (optional)
curl -s http://localhost:18789 > /dev/null && echo "✅ Gateway" || echo "❌ Gateway"

Remote Access via Tailscale

If you want to access LordClaw from another device, keep it on a private network. Tailscale is the recommended option.

Install Tailscale on both machines
Open LordClaw at http://<tailscale-ip>:3333 or http://<magic-dns>:3333
If the OpenClaw gateway is exposed through Tailscale Serve, set the Gateway URL in LordClaw to wss://<magic-dns>

Optional Tailscale Serve example

Use this when you want HTTPS URLs on your tailnet instead of raw local ports. Run these on the machine running OpenClaw and LordClaw, and replace <magic-dns> with that machine’s Tailscale name.

# LordClaw dashboard on https://<magic-dns>:4443
tailscale serve --bg --https=4443 / http://127.0.0.1:3333
 
# OpenClaw gateway on https://<magic-dns> (port 443)
tailscale serve --bg --https=443 / http://127.0.0.1:18789

Then use:

Dashboard URL: https://<magic-dns>:4443
Gateway URL: wss://<magic-dns>

Check the current Tailscale Serve mappings:

tailscale serve status

Remove a specific mapping:

tailscale serve --https=4443 off
tailscale serve --https=443 off

Reset all mappings:

tailscale serve reset

Updating

To update to the latest version:

cd lordclaw
git pull
npm install
npx prisma migrate dev    # apply any new migrations
npm run build              # rebuild for production

Then restart the server (or it will restart automatically if using a Launch Agent / systemd with KeepAlive).

Introduction Getting Started