npm package: @sylphx/runner
Description: Self-hosted runner agent for Sylphx Platform
Latest version: 0.1.0

# @sylphx/runner

Sylphx self-hosted runner agent. Execute builds on your own infrastructure — macOS (for iOS/macOS builds), Windows (for UWP/Windows apps), or Linux.

## Why self-hosted runners?

- **iOS/macOS builds**: Apple Silicon or Intel hardware required
- **Windows/UWP builds**: Windows 10/11 or Server required
- **Private dependencies**: Access internal registries behind your firewall
- **Custom toolchains**: Use tools not available on hosted builders
- **Cost control**: Use your own hardware for heavy build workloads

## Installation

### macOS & Linux

```bash
curl -sL https://sylphx.com/install/runner | sh
```

Or via npm:

```bash
npm install -g @sylphx/runner
```

### Windows

```powershell
winget install Sylphx.Runner
```

Or via npm:

```powershell
npm install -g @sylphx/runner
```

## Quick Start

### 1. Get a registration token

In the Sylphx Console, go to **Org Settings → Runners → Add Runner**.

Copy the one-time registration token.

### 2. Register your machine

```bash
sylphx-runner register --registration-token sxr_reg_<your-token>
```

This saves a long-lived runner token to `~/.sylphx-runner/config.json`.

### 3. Start the runner

```bash
sylphx-runner start
```

Or pass the token inline (useful for CI/server environments):

```bash
SYLPHX_RUNNER_TOKEN="sxr_run_<your-token>" sylphx-runner start
```

### Windows equivalent

```powershell
$env:SYLPHX_RUNNER_TOKEN="sxr_run_<your-token>"
sylphx-runner start
```

## Commands

| Command | Description |
|---------|-------------|
| `sylphx-runner register` | Register this machine (one-time setup) |
| `sylphx-runner start` | Start the runner agent |
| `sylphx-runner status` | Check connectivity and configuration |

### `register` options

| Flag | Description |
|------|-------------|
| `--registration-token <token>` | **(required)** One-time token from Console |
| `--name <name>` | Friendly name (default: `linux-runner`, `darwin-runner`, etc.) |
| `--api-url <url>` | Platform URL (default: `https://sylphx.com`) |

### `start` options

| Flag | Description |
|------|-------------|
| `--token <token>` | Runner token (overrides env var and saved config) |
| `--api-url <url>` | Platform URL (overrides `SYLPHX_API_URL` env var) |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `SYLPHX_RUNNER_TOKEN` | Runner token (set after `register`, or from Console) |
| `SYLPHX_API_URL` | Platform base URL (default: `https://sylphx.com`) |

## How it works

1. Runner connects to the platform and sends a heartbeat every 30 seconds
2. Runner long-polls `GET /runner/jobs/poll` for pending build jobs
3. When a job arrives:
   - `git clone` the repository
   - `git checkout` specific commit (if provided)
   - Execute the build command
   - Stream stdout/stderr back to the platform in real-time
   - Report exit code and status
4. Runner loops back to polling

## Running as a service

### macOS (launchd)

Create `/Library/LaunchDaemons/com.sylphx.runner.plist`:

```xml
<?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.sylphx.runner</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/sylphx-runner</string>
    <string>start</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>SYLPHX_RUNNER_TOKEN</key>
    <string>sxr_run_YOUR_TOKEN_HERE</string>
  </dict>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/var/log/sylphx-runner.log</string>
  <key>StandardErrorPath</key>
  <string>/var/log/sylphx-runner.err</string>
</dict>
</plist>
```

```bash
sudo launchctl load /Library/LaunchDaemons/com.sylphx.runner.plist
```

### Linux (systemd)

Create `/etc/systemd/system/sylphx-runner.service`:

```ini
[Unit]
Description=Sylphx Runner Agent
After=network.target

[Service]
Type=simple
User=runner
Environment=SYLPHX_RUNNER_TOKEN=sxr_run_YOUR_TOKEN_HERE
ExecStart=/usr/local/bin/sylphx-runner start
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl enable --now sylphx-runner
```

### Windows (Task Scheduler / NSSM)

Using NSSM:

```powershell
nssm install SylphxRunner "C:\Program Files\nodejs\node_modules\.bin\sylphx-runner" start
nssm set SylphxRunner AppEnvironmentExtra "SYLPHX_RUNNER_TOKEN=sxr_run_YOUR_TOKEN"
nssm start SylphxRunner
```

## Security

- **Registration tokens** are one-time-use. Once a runner registers, the token is consumed and a long-lived runner token is issued.
- **Runner tokens** (`sxr_run_*`) are stored at `~/.sylphx-runner/config.json` with permissions `600`.
- Communication is over HTTPS only.
- Build environments receive only the env vars explicitly set for that job — no platform secrets are leaked.

## Requirements

- Node.js 18+ or the prebuilt binary
- `git` available in PATH
- Internet access to `https://sylphx.com` (or your self-hosted platform URL)