Skip to main content
IronClaw can install itself as an OS-native background service so the agent keeps running after you close your terminal and starts again when you log in. The installed unit runs ironclaw serve.
  • macOS — a launchd user agent labelled com.ironclaw.reborn in ~/Library/LaunchAgents
  • Linux — a systemd user unit in ~/.config/systemd/user
This page does not apply to a NEAR AI hosted instance. ironclaw service talks to a user service manager (systemctl --user), which a hosted instance doesn’t provide, so every service subcommand fails there — including restart.On a hosted instance the agent is already running and is managed for you. Start, stop, and restart it from the Agent Dashboard. SSH is for running ironclaw config and other read-only commands, not for lifecycle control.
Onboarding offers to do this for you in an interactive session. You can also manage it directly.

​
Managing the Service

restart errors if the service isn’t installed, rather than silently installing it.

​
Logs

The service writes its output to your IronClaw home:
Raise the log level with IRONCLAW_REBORN_LOG before starting the service:

​
Reaching the Agent

The service runs serve with your configured host and port, so the web interface is at http://127.0.0.1:3000 unless you changed it. Set the port in your configuration file rather than on the command line, since the unit doesn’t take flags:
The service runs as your user, not as root, so it has access to the same OS keychain entry that holds your master key. On a headless host without a keychain, supply IRONCLAW_REBORN_SECRET_MASTER_KEY in the service environment instead.

​
Troubleshooting

If the service starts and immediately stops, run the same command in the foreground to see the error:
The most common cause is a foreground ironclaw serve still holding the port — the service runs serve itself, so only one of them can bind at a time. Stop the foreground process and start the service again. Other causes are a missing inference provider credential, or a master key that can’t be read because the keychain is locked.