Keep the CommandChain app running

A computer shows Online only while the CommandChain app runs on it. The installer sets the app to run in the background and to start again when you sign in, wherever the computer allows that. You do not need to keep a terminal open.

The commands on this page are called commandchain-runner; that is the CommandChain app.

Check on it

Run commandchain-runner in a terminal on that computer, and follow what it shows. On Windows, use a PowerShell window opened after the install finished: the install adds the app to your Path for new windows only. If it says commandchain-runner is not recognized, see Troubleshooting.

It prints the computer name and the agents it found, then what the app is doing. Text in angle brackets is filled in by your computer. When all is well, the end of the output looks like this:

✔ CommandChain is running in the background and connected as <name>.
  Open CommandChain:  <link>
  Restart it:         <command>
  Log:                <log file>

If the line starts with ! and says the app “has not reached” the server since a time, the app is running but cannot reach CommandChain. Check the computer’s network. The app keeps trying and reconnects by itself.

If the app is not running, the same command starts it in the background and prints “Starting CommandChain in the background…” first. If the computer is not connected to your account yet, it shows a code to approve first.

For the same facts as a short list, without starting anything, run commandchain-runner status. Its state line says whether the app is connected and when it last checked in.

Restart, stop and start

Restarting ends any agent turn in progress, so do it when no session is working.

The restart command for your computer is the one commandchain-runner status prints after Restart it:. The commands below are the same ones.

To start the app again after you stop it, run commandchain-runner. What happens until then depends on the system:

macOS and Linux: the app stays stopped until you run commandchain-runner, sign in again or restart the computer.
Windows: the app stays stopped, also after you sign in again or restart, until you run commandchain-runner.

Restart: launchctl kickstart -k gui/$(id -u)/ai.commandchain.runner

Stop: launchctl kill SIGTERM gui/$(id -u)/ai.commandchain.runner

Log: ~/Library/Logs/commandchain-runner/runner.log. Follow it with tail -f ~/Library/Logs/commandchain-runner/runner.log.

Restart: systemctl --user restart commandchain-runner

Stop: systemctl --user stop commandchain-runner

Log: ~/.local/state/commandchain-runner/runner.log. Follow it with tail -f ~/.local/state/commandchain-runner/runner.log. If you set XDG_STATE_HOME, the log is in $XDG_STATE_HOME/commandchain-runner/ instead.

The installer also turns on lingering for your user (loginctl enable-linger), so the app keeps running after you sign out. If that is not allowed, the installer says so, and the app runs only while you are signed in.

The background app is a Task Scheduler task named CommandChain- followed by your Windows user name. It starts when you sign in to Windows and runs without a window.

In your user name, every character other than letters, digits, ., _ and - becomes - in the task name. Repeated - are joined into one, and - at the start or end is removed. For the user Ana Lopez, the task is CommandChain-Ana-Lopez. Replace <task> below with your task name, or copy the restart command commandchain-runner status prints.

Restart: Stop-ScheduledTask -TaskName '<task>'; Start-ScheduledTask -TaskName '<task>'

Stop: Disable-ScheduledTask -TaskName '<task>' | Out-Null; Stop-ScheduledTask -TaskName '<task>'

The restart command works only while the task is on. After you stop it this way, start it with commandchain-runner, which turns the task back on.

Log: %LOCALAPPDATA%\CommandChain\logs\commandchain.log. Follow it with Get-Content "$env:LOCALAPPDATA\CommandChain\logs\commandchain.log" -Tail 50 -Wait.

When it stops by itself

If the app crashes, the computer starts it again: within seconds on macOS and Linux, and within 5 minutes on Windows.

It stops, and stays stopped, when CommandChain no longer accepts this computer’s connection for 5 minutes. The log shows these lines:

CommandChain refused this computer's pairing (status <code>). Retrying. After 5 minutes it must be paired again.
CommandChain no longer accepts this computer's pairing. This happens when the computer is removed in the CommandChain app. Run commandchain-runner in a terminal to pair it again.

Run commandchain-runner to connect it again with a new code.

Computers without background apps

Some computers do not allow a background app for your user: a Mac with nobody signed in to the desktop, a Linux login after su or sudo, a Linux system without systemd, or a Windows PC that does not allow background tasks for your account. The installer explains why and runs the app in the terminal instead:

CommandChain is running in this window. Keep it open: closing it disconnects this computer.

Closing the window, signing out or restarting stops the app. Run commandchain-runner to start it again.

To switch to the background app later, run the install command again from a normal desktop or SSH login. To switch from the background app to a terminal, run the install command with --no-service (Windows: -NoService). See Update or uninstall for the commands with options.

One copy per computer

Only one copy of the app runs on each computer. Starting a second one prints:

CommandChain is already running on this computer (pid <pid>). Run commandchain-runner to check on it.

When the app starts again, it tries to reopen the same agent conversations, so your sessions carry on. If a session cannot be resumed, it stops and shows why.

While the computer sleeps, it shows Offline. Messages you send wait until it wakes up.

For a more detailed log to send with a problem report, see Get help.