nullclaw service

Manage nullclaw as a system background service

The nullclaw service command manages nullclaw as a background service on your operating system, enabling auto-start and persistent operation.

Subcommands

nullclaw service install   # Install service (systemd/launchd/Windows SCM)
nullclaw service start     # Start the service
nullclaw service stop      # Stop the service
nullclaw service status    # Check service status
nullclaw service uninstall # Remove the service

Platform Support

Platform	Service Manager	Config Location
Linux	systemd	~/.config/systemd/user/nullclaw.service
macOS	launchd	~/Library/LaunchAgents/com.nullclaw.agent.plist
Windows	Service Control Manager	Registry

Installation

1. Install the service

   nullclaw service install
   

   This creates the appropriate service file for your platform.

2. Start the service

   nullclaw service start
   

   The service starts nullclaw gateway in the background.

3. Verify it's running

   nullclaw service status
   

   Expected output:

   ● nullclaw.service - NullClaw AI Assistant
      Loaded: loaded
      Active: active (running) since ...
   

Service Configuration

Linux (systemd)

Service file at ~/.config/systemd/user/nullclaw.service:

[Unit]
Description=NullClaw AI Assistant
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/nullclaw gateway
Restart=on-failure
RestartSec=10
Environment="HOME=%h"
WorkingDirectory=%h/.nullclaw
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

Manual management:

# Enable auto-start on login
systemctl --user enable nullclaw

# Start now
systemctl --user start nullclaw

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

# Stop
systemctl --user stop nullclaw

# Disable auto-start
systemctl --user disable nullclaw

macOS (launchd)

Plist at ~/Library/LaunchAgents/com.nullclaw.agent.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.nullclaw.agent</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/nullclaw</string>
    <string>gateway</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>WorkingDirectory</key>
  <string>/Users/YOU/.nullclaw</string>
  <key>StandardOutPath</key>
  <string>/Users/YOU/.nullclaw/logs/stdout.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/YOU/.nullclaw/logs/stderr.log</string>
</dict>
</plist>

Manual management:

# Load (start and enable auto-start)
launchctl load ~/Library/LaunchAgents/com.nullclaw.agent.plist

# Unload (stop and disable)
launchctl unload ~/Library/LaunchAgents/com.nullclaw.agent.plist

# Check status
launchctl list | grep nullclaw

# View logs
tail -f ~/.nullclaw/logs/stdout.log

Logging

Linux (systemd)

Logs go to systemd journal:

# View all logs
journalctl --user -u nullclaw

# Follow logs
journalctl --user -u nullclaw -f

# Last 100 lines
journalctl --user -u nullclaw -n 100

# Since yesterday
journalctl --user -u nullclaw --since yesterday

macOS (launchd)

Logs go to files:

# Standard output
tail -f ~/.nullclaw/logs/stdout.log

# Standard error
tail -f ~/.nullclaw/logs/stderr.log

Auto-Restart

The service automatically restarts on failure:

• Linux: Restart=on-failure, RestartSec=10
• macOS: KeepAlive=true
• Windows: Recovery settings

Troubleshooting

Service won’t start

# Check service status
nullclaw service status

# View recent logs
journalctl --user -u nullclaw -n 50

# Verify nullclaw binary exists
which nullclaw

# Test gateway manually
nullclaw gateway

Service starts but gateway fails

# Check config validity
nullclaw doctor

# Verify port not in use
lsof -i :3000  # Linux/macOS

# Check permissions
ls -la ~/.nullclaw/config.json

systemd user service (Linux)

User services require “lingering” to run when you’re not logged in:

loginctl enable-linger $USER

Examples

Install and start

# Install
nullclaw service install

# Start
nullclaw service start

# Verify
nullclaw service status
● nullclaw.service - NullClaw AI Assistant
   Active: active (running)

View logs

# Linux
journalctl --user -u nullclaw -f

# macOS
tail -f ~/.nullclaw/logs/stdout.log

Stop and uninstall

# Stop
nullclaw service stop

# Uninstall
nullclaw service uninstall

See Also

• Gateway - Gateway command reference
• Deployment - Service deployment guide
• Doctor - Diagnostics tool