> ## 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.

# 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

```bash theme={null}
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

<Steps>
  <Step title="Install the service">
    ```bash theme={null}
    nullclaw service install
    ```

    This creates the appropriate service file for your platform.
  </Step>

  <Step title="Start the service">
    ```bash theme={null}
    nullclaw service start
    ```

    The service starts `nullclaw gateway` in the background.
  </Step>

  <Step title="Verify it's running">
    ```bash theme={null}
    nullclaw service status
    ```

    Expected output:

    ```
    ● nullclaw.service - NullClaw AI Assistant
       Loaded: loaded
       Active: active (running) since ...
    ```
  </Step>
</Steps>

## Service Configuration

### Linux (systemd)

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

```ini theme={null}
[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:

```bash theme={null}
# 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 theme={null}
<?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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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)

<Warning>
  User services require "lingering" to run when you're not logged in:

  ```bash theme={null}
  loginctl enable-linger $USER
  ```
</Warning>

## Examples

### Install and start

```bash theme={null}
# Install
nullclaw service install

# Start
nullclaw service start

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

### View logs

```bash theme={null}
# Linux
journalctl --user -u nullclaw -f

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

### Stop and uninstall

```bash theme={null}
# Stop
nullclaw service stop

# Uninstall
nullclaw service uninstall
```

## See Also

* [Gateway](/cli/gateway) - Gateway command reference
* [Deployment](/deployment/service) - Service deployment guide
* [Doctor](/cli/doctor) - Diagnostics tool