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

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

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

```bash theme={null}
# Install the service
ironclaw service install
```

### Output

**macOS:**

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

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

```bash theme={null}
ironclaw service start
```

### Examples

```bash theme={null}
ironclaw service start
```

### Output

**macOS:**

```bash theme={null}
Starting IronClaw service...
✓ Service started
```

**Linux:**

```bash theme={null}
Starting IronClaw service...
✓ Service started
```

***

## ironclaw service stop

Stop the running IronClaw service.

### Syntax

```bash theme={null}
ironclaw service stop
```

### Examples

```bash theme={null}
ironclaw service stop
```

### Output

**macOS:**

```bash theme={null}
Stopping IronClaw service...
✓ Service stopped
```

**Linux:**

```bash theme={null}
Stopping IronClaw service...
✓ Service stopped
```

***

## ironclaw service status

Show the current status of the IronClaw service.

### Syntax

```bash theme={null}
ironclaw service status
```

### Examples

```bash theme={null}
ironclaw service status
```

### Output

**macOS (running):**

```bash theme={null}
IronClaw service status:

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

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

**macOS (stopped):**

```bash theme={null}
IronClaw service status:

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

Start with: ironclaw service start
```

**Linux (running):**

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

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

```bash theme={null}
ironclaw service uninstall
```

### Description

This command:

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

### Examples

```bash theme={null}
ironclaw service uninstall
```

### Output

**macOS:**

```bash theme={null}
Uninstalling IronClaw service...

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

IronClaw service has been uninstalled.
```

**Linux:**

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

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

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

```xml theme={null}
<key>EnvironmentVariables</key>
<dict>
    <key>DATABASE_URL</key>
    <string>postgresql://...</string>
    <key>NEARAI_API_KEY</key>
    <string>your-key</string>
</dict>
```

Reload:

```bash theme={null}
launchctl unload ~/Library/LaunchAgents/com.ironclaw.agent.plist
launchctl load ~/Library/LaunchAgents/com.ironclaw.agent.plist
```

**Linux (systemd):**

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

```ini theme={null}
[Service]
Environment="DATABASE_URL=postgresql://..."
Environment="NEARAI_API_KEY=your-key"
EnvironmentFile=/home/you/workspace/.env
```

Reload:

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

```xml theme={null}
<key>WorkingDirectory</key>
<string>/path/to/workspace</string>
```

**Linux (systemd):**

```ini theme={null}
[Service]
WorkingDirectory=/path/to/workspace
```

## Restart Behavior

### macOS (launchd)

The service automatically restarts if it crashes:

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

```ini theme={null}
Restart=always
RestartSec=10
```

To disable auto-restart:

```ini theme={null}
Restart=no
```

## Troubleshooting

### Service won't start

Check logs:

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

```bash theme={null}
ironclaw run
```

### Service starts but stops immediately

Check for:

* Configuration errors
* Missing dependencies
* Port conflicts

Run diagnostics:

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

```bash theme={null}
chmod 644 ~/.config/systemd/user/ironclaw.service
```

Reload systemd:

```bash theme={null}
systemctl --user daemon-reload
```

### Service not starting on boot (Linux)

Enable lingering for your user:

```bash theme={null}
sudo loginctl enable-linger $USER
```

Verify the service is enabled:

```bash theme={null}
systemctl --user is-enabled ironclaw
```

## Manual Service Management

### macOS (launchd)

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

```bash theme={null}
# 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](/cli/onboard) - Initial configuration
* [doctor](/cli/doctor) - Verify configuration and dependencies
* [config](/cli/config) - View and modify settings