--- url: /en/paas/system-runner.md description: > Guide for system administrators to add and configure build machines (Linux, Mac, Windows) as Runners for Cloud Native Build and Workspaces, covering system-hosted and self-hosted modes with setup scripts. --- ## Overview System administrators can add machines in the `Admin Management Platform` as Runners for `Cloud Native Build`/`Workspaces` functionality, available for users. CNB supports Linux, Mac, and Windows build machines. ### Two Hosting Modes For specific usage, see [Admin Configuration](#adding-runner-to-the-system) and [Runner Configuration](#configuration-process). #### System Hosting (Default) Machines managed by the CNB platform require mutual access between the machine and the platform. Added via `ip:port`. #### Self-Hosting Machines managed by users themselves only require direct access to the CNB platform. Added via a unique identifier. ### Who Can Add Runners * **System administrators**: add Runners under `Admin Console / System Management / Cloud Native Build / Runner Management` to provide platform-wide build capacity. * **Root-organization administrators** (optional): once the system administrator enables the `Allow Custom Runners` toggle, root-organization administrators can self-attach Mac/Windows build machines under `Organization Settings / Build Nodes` for use within that organization only. See [Root-Organization Custom Runners](#root-organization-custom-runners) below. ## System Environment Requirements ### Linux Build Machines * TencentOS 3.2 / TencentOS 3.1 / CentOS 8 and derivatives * Kernel version 5.4+ recommended * docker >= 26.1.5 * Ports 8087 and 8088 must be available and allowed for local listening ### Mac Build Machines * git >= 2.43.0 * Ports 8087 and 8088 must be available and allowed for local listening Since Mac does not support `OverlayFS`, second-read cloning will degrade to normal cloning. ### Windows Build Machines * Recommended Windows 10 or above * git >= 2.43.0 * Ports 8087 and 8088 must be available and allowed for local listening Since Windows does not support `OverlayFS`, second-read cloning will degrade to normal cloning. ## Configuration Process ### ==1. Configure Linux Build Machines (Standard Solution)== @[code-tree title="Initialize RUNNER Scripts" height="800px"](./system-runner) ### ==2. Configure Self-Hosted Build Machines=={.info} #### ==2.1=={.info} Create Self-Hosted RUNNER in Admin Console ::: note Tags must start with `cnb`. ::: ![Create Self-Hosted RUNNER](/images/system-runner/create-system-runner.en.png) ① Download the certificate from the Admin Console. ② Upload the certificate archive to the build machine configuration directory and extract it. * Linux: ==`/etc/orange-ci`== * Mac: ==`$HOME/orange-ci/etc/orange-ci`== * Windows: ==`C:/etc/orange-ci`== ③ The installation script will determine whether to enable TLS verification based on the presence of `orange-ci.pem`, `orange-runner.crt`, and `orange-runner.key` in the specified directory. #### ==2.2=={.info} Connect Self-Hosted RUNNER {#self-hosted-runner-onboarding} ::: note ① The build node must be able to access the current CNB site domain. ② After creating the Runner, open `Connection Guide`. For a first installation, click `Get one-time enrollment token` in the dialog. ③ On Windows, pay attention to script and config file encoding to avoid startup failures caused by hidden extensions or BOM headers. ::: ##### Linux 1. \==One-Click Setup Script== ```shell curl -fsSL https://docs.cnbprod.alpha.qq.com/system-runner/scripts/linux.sh \ | CONNECTOR_ENDPOINT=wss://connector.cnbprod.alpha.qq.com \ SELF_HOSTED_ID=xxxx-xxxx-xxxx ENROLLMENT_TOKEN=REPLACE_WITH_TOKEN_FROM_CONNECTION_GUIDE bash ``` 2. \==Configuration and Storage Directories== ```shell Default directories and paths: ① Configuration directory: `/etc/orange-ci` ② RUNNER configuration file: `/etc/orange-ci/runner-config.json` ③ Data storage directory: `/data/orange-ci` How to modify: ① Modify configuration directory: Configure environment variable `ORANGE_RUNNER_CONFIG_DIR` ② Modify data directory: Configure environment variable `ORANGE_RUNNER_DATA_DIR`. ``` 3. \==Other Common Commands== ```shell # Install service orange-runner install # Start service orange-runner start # Stop service orange-runner stop # Uninstall service orange-runner uninstall # Remove global command rm /usr/local/bin/orange-runner # Check service running status orange-runner status # View logs tail -f /data/orange-runner/logs/app.log ``` ##### Mac 1. \==One-Click Setup Script== ```shell curl -fsSL https://docs.cnbprod.alpha.qq.com/system-runner/scripts/mac.sh \ | sudo env CONNECTOR_ENDPOINT=wss://connector.cnbprod.alpha.qq.com \ SELF_HOSTED_ID=xxxx-xxxx-xxxx bash ``` 2. \==Configuration and Storage Directories== ```shell Default directories and paths: ① Configuration directory: `$HOME/orange-ci/etc/orange-ci` ② RUNNER configuration file: `$HOME/orange-ci/etc/orange-ci/runner-config.json` ③ Data storage directory: `$HOME/orange-ci/data/orange-ci` How to modify: ① Modify configuration directory: Configure environment variable `ORANGE_RUNNER_CONFIG_DIR` ② Modify data directory: Configure environment variable `ORANGE_RUNNER_DATA_DIR`. ``` 2. \==Other Common Commands== ```shell # Install service orange-runner install # Start service orange-runner start # Stop service orange-runner stop # Uninstall service orange-runner uninstall # Remove global command rm /usr/local/bin/orange-runner # Check service running status orange-runner status # View logs tail -f $HOME/orange-ci/data/orange-runner/logs/app.log ``` ##### Windows 1. \==One-Click Setup Script== ```shell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Confirm:$False -Force invoke-webrequest https://docs.cnbprod.alpha.qq.com/system-runner/scripts/windows.ps1 \ -outfile windows.ps1 $env:CONNECTOR_ENDPOINT='wss://connector.cnbprod.alpha.qq.com' $env:SELF_HOSTED_ID='xxxx-xxxx-xxxx' $env:ENROLLMENT_TOKEN='REPLACE_WITH_TOKEN_FROM_CONNECTION_GUIDE' ./windows.ps1 ``` 2. \==Configuration and Storage Directories== ```shell Default directories and paths: ① Configuration directory: `C:/etc/orange-ci` ② RUNNER configuration file: `C:/etc/orange-ci/runner-config.json` ③ Data storage directory: `C:/data/orange-ci` How to modify: ① Modify configuration directory: Configure environment variable `ORANGE_RUNNER_CONFIG_DIR` ② Modify data directory: Configure environment variable `ORANGE_RUNNER_DATA_DIR`. ``` 3. \==Common Commands== ```shell # cd to the directory where orange-runner.exe is located cd $HOME\Downloads\orange-runner # Start service .\orange-runner.exe start # Stop service .\orange-runner.exe stop # Uninstall service .\orange-runner.exe uninstall # Delete exe file Remove-Item -Path .\orange-runner.exe # Check service running status .\orange-runner.exe status # View logs Get-Content 'C:\data\orange-runner\logs\app.log' -Wait -Tail 10 ``` ## Root-Organization Custom Runners In addition to system-administrator-managed build nodes, the platform also allows root-organization administrators to self-attach Mac/Windows build machines as resources dedicated to that organization. ### 1. System Administrator Enables the Toggle Open `Admin Console / System Management / Cloud Native Build / Custom Runner` and turn on the `Allow Custom Runners` toggle. Once enabled, every root organization gains a `Build Nodes` entry in `Organization Settings`, where root-organization administrators can self-attach Runners. ### 2. Root-Organization Administrator Connects the Build Machine 1. Open `Root Organization / Organization Settings / Build Nodes`, click `+ Add Runner`, and fill in name and tags. 2. The new node starts in the `Offline` state. Open `Connection Guide`, click `Get one-time enrollment token`, and copy the generated complete command. The token is valid for one hour; no manual replacement of `SELF_HOSTED_ID` or token assembly is required. 3. Run the script for the matching platform (Mac/Windows) on the target build machine. The node becomes `Online` once it successfully connects. If Connection Guide reports an expired secret or local `state.json` is lost, click `Reset runner and get install command` and reinstall with the new command. Do not reuse an old command or token. ::: tip When does a reset take effect? The server caches Runner credentials for up to 5 minutes. Operations such as resetting a Runner or clearing its machine fingerprint take full effect once that cache expires. Until then the original machine may still connect and a new machine may be briefly rejected. This is expected — just wait and retry instead of repeating the operation. ::: The script content, configuration directories, and common commands are identical to those described in [Connect Self-Hosted RUNNER](#self-hosted-runner-onboarding) above. ### 3. Scheduling in `.cnb.yml` See the user-side documentation [Build Node - Root-Organization Custom Runners](../build/build-node.md#root-organization-custom-runners). ### Limitations * Only **Mac** and **Windows** build machines are supported; Linux self-hosted nodes are still attached by the system administrator. * The custom build machine must be able to **reach the CNB site** (for node registration, heartbeat reporting, pulling pipeline tasks, and uploading logs/artifacts). If the machine sits on an internal network, make sure the required egress policy is in place. * Custom Runners do not enable Docker by default: `runner.cpus` has no effect, and image-based build environments cannot be used. * For **Cloud Native Build only**; cannot be used for Workspaces (remote development) tasks. * Advanced capabilities such as scoping a Runner's allowed groups/projects and certificate placement are identical to system-level self-hosted Runners. ## FAQ ### Linux Build Machines 1. When building multi-platform images with `docker buildx`, building ARM images fails with: `Error while loading /usr/sbin/dpkg-split: No such file or directory` Solution: ```bash docker run --rm --privileged multiarch/qemu-user-static --reset -p yes --credential yes ``` 2. `git clone` works on the host but times out in pipeline containers. Cause: IPv4 forwarding must be enabled. `cat /proc/sys/net/ipv4/ip_forward` should return `1`. If not enabled, edit with the following command: ### Self-Hosted Build Machines 1. When is it appropriate to use self-hosted RUNNER? * Build requirements for Windows and Mac. * Network requirements where CNB-provided build machines cannot access your network, but self-hosted machines can access the target network. 2. What can self-hosted runners do? What can't they do? * Can only run commands on bare metal. * Can only run CI tasks. * Cannot run remote development tasks. 3. Can self-hosted RUNNER usage be restricted to specific repositories and organizations to prevent machine abuse? ```json { "allowUseThisRunner": { "groups": [], "projects": [] } } ``` Add this configuration in runner-config.json, using exact comparison. If it doesn't meet expectations, check the runner's logs.