ironclaw service - IronClaw

Overview

The ironclaw service command manages IronClaw as a system service, allowing it to run automatically in the background and start on boot.

macOS: Uses launchd (Launch Agent)
Linux: Uses systemd (user service)
Windows: Not currently supported

Subcommands

install

Install IronClaw as an OS service:

ironclaw service install

This command:

Creates a service unit file (launchd plist or systemd unit)
Configures the service to start on boot
Sets up logging to system journal
Installs the service for the current user

macOS output:

✓ Created Launch Agent: ~/Library/LaunchAgents/com.ironclaw.agent.plist
✓ Service installed successfully

To start now: ironclaw service start
To enable on boot: launchctl load ~/Library/LaunchAgents/com.ironclaw.agent.plist

Linux output:

✓ Created systemd unit: ~/.config/systemd/user/ironclaw.service
✓ Service installed successfully

To start now: ironclaw service start
To enable on boot: systemctl --user enable ironclaw.service

start

Start the installed service:

ironclaw service start

Output:

✓ Service started successfully

To view logs:
  macOS: log show --predicate 'processImagePath contains "ironclaw"'
  Linux: journalctl --user -u ironclaw.service -f

stop

Stop the running service:

ironclaw service stop

Output:

✓ Service stopped

status

Check service status:

ironclaw service status

Output (running):

IronClaw Service Status

Status:       running
PID:          12345
Uptime:       2 hours 34 minutes
Memory:       145 MB

Enabled:      yes (starts on boot)
Unit file:    ~/.config/systemd/user/ironclaw.service

Logs:
  journalctl --user -u ironclaw.service

Output (stopped):

IronClaw Service Status

Status:       stopped
Enabled:      yes (will start on boot)
Unit file:    ~/.config/systemd/user/ironclaw.service

To start: ironclaw service start

Output (not installed):

IronClaw Service Status

Status:       not installed

To install: ironclaw service install

uninstall

Remove the OS service:

ironclaw service uninstall

Output:

✓ Service stopped
✓ Service uninstalled
✓ Removed unit file

This removes the service configuration but does not delete your data or configuration files.

Service Configuration

macOS (launchd)

The Launch Agent plist is created at:

~/Library/LaunchAgents/com.ironclaw.agent.plist

Example 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.ironclaw.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/ironclaw</string>
        <string>run</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/ironclaw.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/ironclaw.err</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin</string>
    </dict>
</dict>
</plist>

Manual launchd commands:

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

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

# Start
launchctl start com.ironclaw.agent

# Stop
launchctl stop com.ironclaw.agent

# View status
launchctl list | grep ironclaw

Linux (systemd)

The systemd unit is created at:

~/.config/systemd/user/ironclaw.service

Example unit file:

[Unit]
Description=IronClaw AI Agent
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/ironclaw run
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

Manual systemd commands:

# Reload systemd configuration
systemctl --user daemon-reload

# Enable (start on boot)
systemctl --user enable ironclaw.service

# Disable (don't start on boot)
systemctl --user disable ironclaw.service

# Start
systemctl --user start ironclaw.service

# Stop
systemctl --user stop ironclaw.service

# Restart
systemctl --user restart ironclaw.service

# View status
systemctl --user status ironclaw.service

# View logs
journalctl --user -u ironclaw.service -f

Environment Variables

The service reads environment variables from:

~/.ironclaw/.env (loaded automatically)
System environment (for systemd: EnvironmentFile= directive)
Service configuration (for launchd: EnvironmentVariables dict)

Ensure your .env file contains all required variables like DATABASE_URL, NEARAI_API_KEY, and SECRETS_MASTER_KEY.

Logging

macOS Logs

View logs using the log command:

# Real-time logs
log stream --predicate 'processImagePath contains "ironclaw"'

# Historical logs
log show --predicate 'processImagePath contains "ironclaw"' --last 1h

# Errors only
log show --predicate 'processImagePath contains "ironclaw" and messageType == error' --last 1h

Or check the log files directly:

tail -f /tmp/ironclaw.log
tail -f /tmp/ironclaw.err

Linux Logs

View logs using journalctl:

# Real-time logs
journalctl --user -u ironclaw.service -f

# Last 100 lines
journalctl --user -u ironclaw.service -n 100

# Logs since boot
journalctl --user -u ironclaw.service -b

# Errors only
journalctl --user -u ironclaw.service -p err

# Logs from the last hour
journalctl --user -u ironclaw.service --since "1 hour ago"

Auto-start on Boot

macOS

To enable auto-start:

launchctl load ~/Library/LaunchAgents/com.ironclaw.agent.plist

To disable auto-start:

launchctl unload ~/Library/LaunchAgents/com.ironclaw.agent.plist

Linux

To enable auto-start:

systemctl --user enable ironclaw.service

To disable auto-start:

systemctl --user disable ironclaw.service

Troubleshooting

Service won't start

Check logs for errors:macOS:

cat /tmp/ironclaw.err
log show --predicate 'processImagePath contains "ironclaw"' --last 10m

Linux:

journalctl --user -u ironclaw.service -n 50

Common issues:

Missing environment variables in .env
Database connection failure
Invalid configuration

Service stops unexpectedly

The service will automatically restart on failure. Check logs for crash reasons:Linux:

systemctl --user status ironclaw.service
journalctl --user -u ironclaw.service -p err

If the service crashes repeatedly, it may be disabled by systemd. Re-enable:

systemctl --user reset-failed ironclaw.service
systemctl --user start ironclaw.service

Service doesn't start on boot

macOS: Ensure the plist is loaded:

launchctl load ~/Library/LaunchAgents/com.ironclaw.agent.plist

Linux: Ensure the service is enabled:

systemctl --user enable ironclaw.service

You may also need to enable user lingering:

sudo loginctl enable-linger $USER

Cannot find ironclaw binary

Ensure ironclaw is in your PATH and the service unit has the correct path:Find binary location:

which ironclaw

Update service unit (Linux): Edit ~/.config/systemd/user/ironclaw.service and update ExecStart=Update service unit (macOS): Edit ~/Library/LaunchAgents/com.ironclaw.agent.plist and update ProgramArguments

ironclaw run

Run the agent directly (foreground)

ironclaw status

Check system health

ironclaw doctor

Diagnose issues

​Overview

​Subcommands

​install

​start

​stop

​status

​uninstall

​Service Configuration

​macOS (launchd)

​Linux (systemd)

​Environment Variables

​Logging

​macOS Logs

​Linux Logs

​Auto-start on Boot

​macOS

​Linux

​Troubleshooting

​Related Commands

ironclaw run

ironclaw status

ironclaw doctor

Overview

Subcommands

install

start

stop

status

uninstall

Service Configuration

macOS (launchd)

Linux (systemd)

Environment Variables

Logging

macOS Logs

Linux Logs

Auto-start on Boot

macOS

Linux

Troubleshooting

Related Commands