ironclaw service

Manage IronClaw as an OS service (launchd/systemd)

ironclaw service

Manage IronClaw as an OS service. This allows the agent to run in the background and start automatically on system boot.

• macOS: Uses launchd
• Linux: Uses systemd

Subcommands

• install - Install the OS service
• start - Start the service
• stop - Stop the service
• status - Show service status
• uninstall - Uninstall the service

---

ironclaw service install

Install IronClaw as an OS service.

Syntax

ironclaw service install

Description

This command:

1. Detects your operating system (macOS or Linux)
2. Generates the appropriate service configuration file
3. Installs the service unit file
4. Configures the service to start on boot

The service will run ironclaw run with your current configuration.

macOS (launchd)

Creates: ~/Library/LaunchAgents/com.ironclaw.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.ironclaw.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/ironclaw</string>
        <string>run</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/you/.ironclaw/service.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/you/.ironclaw/service-error.log</string>
</dict>
</plist>

Linux (systemd)

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

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

[Service]
Type=simple
ExecStart=/path/to/ironclaw run
Restart=always
RestartSec=10
StandardOutput=append:/home/you/.ironclaw/service.log
StandardError=append:/home/you/.ironclaw/service-error.log

[Install]
WantedBy=default.target

Examples

# Install the service
ironclaw service install

Output

macOS:

Installing IronClaw service for macOS (launchd)...

✓ Service file created: ~/Library/LaunchAgents/com.ironclaw.agent.plist
✓ Service loaded

The service will start automatically on login.

Commands:
  Start:  ironclaw service start
  Stop:   ironclaw service stop
  Status: ironclaw service status
  Logs:   tail -f ~/.ironclaw/service.log

Linux:

Installing IronClaw service for Linux (systemd)...

✓ Service file created: ~/.config/systemd/user/ironclaw.service
✓ Daemon reloaded
✓ Service enabled

The service will start automatically on boot.

Commands:
  Start:  ironclaw service start
  Stop:   ironclaw service stop
  Status: ironclaw service status
  Logs:   journalctl --user -u ironclaw -f

---

ironclaw service start

Start the IronClaw service.

Syntax

ironclaw service start

Examples

ironclaw service start

Output

macOS:

Starting IronClaw service...
✓ Service started

Linux:

Starting IronClaw service...
✓ Service started

---

ironclaw service stop

Stop the running IronClaw service.

Syntax

ironclaw service stop

Examples

ironclaw service stop

Output

macOS:

Stopping IronClaw service...
✓ Service stopped

Linux:

Stopping IronClaw service...
✓ Service stopped

---

ironclaw service status

Show the current status of the IronClaw service.

Syntax

ironclaw service status

Examples

ironclaw service status

Output

macOS (running):

IronClaw service status:

● com.ironclaw.agent
   Loaded: loaded
   Active: running
   PID: 12345
   Uptime: 2 hours

Logs: tail -f ~/.ironclaw/service.log

macOS (stopped):

IronClaw service status:

● com.ironclaw.agent
   Loaded: loaded
   Active: stopped

Start with: ironclaw service start

Linux (running):

IronClaw service status:

● ironclaw.service - IronClaw AI Assistant
   Loaded: loaded (/home/you/.config/systemd/user/ironclaw.service)
   Active: active (running) since Mon 2024-01-15 14:23:45 UTC; 2h 15min ago
 Main PID: 12345 (ironclaw)
   CGroup: /user.slice/user-1000.slice/[e-mail]/ironclaw.service
           └─12345 /usr/local/bin/ironclaw run

Jan 15 14:23:45 hostname systemd[1234]: Started IronClaw AI Assistant.
Jan 15 14:23:46 hostname ironclaw[12345]: Starting IronClaw agent...

Logs: journalctl --user -u ironclaw -f

Linux (stopped):

IronClaw service status:

● ironclaw.service - IronClaw AI Assistant
   Loaded: loaded (/home/you/.config/systemd/user/ironclaw.service)
   Active: inactive (dead)

Start with: ironclaw service start

---

ironclaw service uninstall

Uninstall the IronClaw service and remove service files.

Syntax

ironclaw service uninstall

Description

This command:

1. Stops the service if running
2. Unloads/disables the service
3. Removes the service configuration file

Examples

ironclaw service uninstall

Output

macOS:

Uninstalling IronClaw service...

✓ Service stopped
✓ Service unloaded
✓ Service file removed: ~/Library/LaunchAgents/com.ironclaw.agent.plist

IronClaw service has been uninstalled.

Linux:

Uninstalling IronClaw service...

✓ Service stopped
✓ Service disabled
✓ Service file removed: ~/.config/systemd/user/ironclaw.service
✓ Daemon reloaded

IronClaw service has been uninstalled.

Service Logs

macOS (launchd)

Logs are written to:

• Standard output: ~/.ironclaw/service.log
• Standard error: ~/.ironclaw/service-error.log

# Follow logs
tail -f ~/.ironclaw/service.log

# View errors
tail -f ~/.ironclaw/service-error.log

# View all logs
cat ~/.ironclaw/service*.log

Linux (systemd)

Logs are managed by journald:

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

# View recent logs
journalctl --user -u ironclaw -n 100

# View logs since boot
journalctl --user -u ironclaw -b

# View logs with timestamps
journalctl --user -u ironclaw -o short-iso

Logs are also written to:

• ~/.ironclaw/service.log
• ~/.ironclaw/service-error.log

Environment Variables

The service inherits environment variables from:

1. System environment (limited in service context)
2. User environment (shell profile not loaded)
3. .env file in the working directory

Setting Service Environment

macOS (launchd):

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

<key>EnvironmentVariables</key>
<dict>
    <key>DATABASE_URL</key>
    <string>postgresql://...</string>
    <key>NEARAI_API_KEY</key>
    <string>your-key</string>
</dict>

Reload:

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

Linux (systemd):

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

[Service]
Environment="DATABASE_URL=postgresql://..."
Environment="NEARAI_API_KEY=your-key"
EnvironmentFile=/home/you/workspace/.env

Reload:

systemctl --user daemon-reload
systemctl --user restart ironclaw

Working Directory

The service runs in the directory where ironclaw is installed. To specify a different working directory:

macOS (launchd):

<key>WorkingDirectory</key>
<string>/path/to/workspace</string>

Linux (systemd):

[Service]
WorkingDirectory=/path/to/workspace

Restart Behavior

macOS (launchd)

The service automatically restarts if it crashes:

<key>KeepAlive</key>
<true/>

To disable auto-restart, edit the plist and set to <false/>.

Linux (systemd)

The service restarts after 10 seconds if it fails:

Restart=always
RestartSec=10

To disable auto-restart:

Restart=no

Troubleshooting

Service won’t start

Check logs:

# macOS
tail -f ~/.ironclaw/service-error.log

# Linux
journalctl --user -u ironclaw -n 50

Common issues:

• Missing environment variables
• Database connection failure
• Permission errors

Test manually first:

ironclaw run

Service starts but stops immediately

Check for:

• Configuration errors
• Missing dependencies
• Port conflicts

Run diagnostics:

ironclaw doctor

Environment variables not working

The service doesn’t load your shell profile (.bashrc, .zshrc, etc.).

Options:

1. Set environment variables in the service unit file (see above)
2. Use a .env file in the working directory
3. Specify EnvironmentFile in systemd service

Permission denied (Linux)

Ensure the service file is readable:

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

Reload systemd:

systemctl --user daemon-reload

Service not starting on boot (Linux)

Enable lingering for your user:

sudo loginctl enable-linger $USER

Verify the service is enabled:

systemctl --user is-enabled ironclaw

Manual Service Management

macOS (launchd)

# Load service
launchctl load ~/Library/LaunchAgents/com.ironclaw.agent.plist

# Unload service
launchctl unload ~/Library/LaunchAgents/com.ironclaw.agent.plist

# List loaded services
launchctl list | grep ironclaw

# View service info
launchctl list com.ironclaw.agent

Linux (systemd)

# Reload daemon
systemctl --user daemon-reload

# Enable service
systemctl --user enable ironclaw

# Disable service
systemctl --user disable ironclaw

# Restart service
systemctl --user restart ironclaw

# View service file
systemctl --user cat ironclaw

Related Commands

• onboard - Initial configuration
• doctor - Verify configuration and dependencies
• config - View and modify settings