Skip to main content

Documentation Index

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

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

​
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/user@1000.service/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
  • onboard - Initial configuration
  • doctor - Verify configuration and dependencies
  • config - View and modify settings

Build docs developers (and LLMs) love

Get started for freeTalk to us