@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

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

Or via npm:

npm install -g @sylphx/runner

Windows

winget install Sylphx.Runner

Or via npm:

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

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

sylphx-runner start

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

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

Windows equivalent

$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 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>

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

Linux (systemd)

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

[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

sudo systemctl enable --now sylphx-runner

Windows (Task Scheduler / NSSM)

Using NSSM:

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)