Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nullclaw/nullclaw/llms.txt

Use this file to discover all available pages before exploring further.

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

PlatformService ManagerConfig Location
Linuxsystemd~/.config/systemd/user/nullclaw.service
macOSlaunchd~/Library/LaunchAgents/com.nullclaw.agent.plist
WindowsService Control ManagerRegistry

​
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