> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiml-code-it.automat-it.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Install and troubleshoot the runner

> Install, check, repair and remove code-it-runner on macOS.

## Install

The installer supports macOS only. You need Node 20 or newer and `kiro-cli` on your PATH. Use the exact command shown on the **Connect your laptop** page:

```bash theme={null}
curl -fsSL https://app.aiml-code-it.automat-it.io/install.sh | sh
```

The script is HTTPS-only, verifies the runner tarball against a published sha256 and refuses to install on a mismatch. It then:

* installs into `~/.code-it/runner` and puts a `code-it-runner` launcher in `~/.code-it/bin`,
* adds `~/.code-it/bin` to your PATH in `~/.zprofile` (and `~/.bash_profile` if it exists),
* opens a browser page to approve this laptop,
* registers a LaunchAgent `io.codeit.runner` that starts at login and restarts on crash,
* registers a second small agent, a watchdog, that runs every two minutes and re-registers the runner if launchd has dropped it.

Open a new terminal afterwards, or run `source ~/.zprofile`.

If you do not use AWS in the agent, you are done. Otherwise choose the AWS profile per project:

```bash theme={null}
code-it-runner aws-profile <project-slug> <aws-profile>
```

The profile name and its credentials stay on your laptop.

## Check it

```bash theme={null}
code-it-runner status
```

Shows the runner version, whether the LaunchAgent is installed, whether a token is stored, the `kiro-cli` path and version, the log directory and the agents the runner knows.

## When the laptop shows offline

**1. Run the doctor**

```bash theme={null}
code-it-runner doctor
```

It reads launchd's state and lists problems. It exits non-zero when the runner is not healthy.

**2. Repair**

```bash theme={null}
code-it-runner repair
```

Re-enables and reloads the LaunchAgent and the watchdog. This fixes the case where launchd marked the runner disabled or dropped it.

**3. Read the logs**

```bash theme={null}
code-it-runner logs --follow
```

**4. Sign in again if the token is rejected**

```bash theme={null}
code-it-runner login --api https://api.aiml-code-it.automat-it.io
```

## Uninstall

```bash theme={null}
code-it-runner uninstall
```

Removes the LaunchAgent and `~/.code-it/runner`. It keeps your `~/code-it` workspaces and `~/.config/code-it` so a reinstall does not force a new sign-in.

## Common problems

| Symptom | Likely cause | Fix |
| - | - | - |
| Installer says Node is missing or too old | Node below 20 | Install Node 20+ from nodejs.org and re-run |
| Installer says `kiro-cli` is not on PATH | Kiro CLI not installed | Install Kiro, sign in, re-run |
| Task stuck at `waiting_for_runner` | Your runner is not connected | `code-it-runner doctor`, then `repair` |
| Agent cannot clone the repo | `gh` not signed in to the org | `gh auth login`, then retry the launch |
| Grid shows `aws_session_expired` | AWS session expired | `aws sso login --profile <aws-profile>` |
| Agent cannot deploy at all | No profile set for the project | `code-it-runner aws-profile <slug> <profile>` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.