A few answers.
And a way to reach a real person.
Where is the app? Nothing opened.
ForgeLight is a menu bar app: no Dock icon, no main window. Its ring appears at the right of the menu bar on launch; click it for the menu. The first time, it opens Settings on its own, because with no runner configured there is nothing else to show.
How does ForgeLight find my runners?
It reads only the folders you choose. Under Settings → Runners, choose a runner's installation folder — the one holding its .runner file and _diag logs — or a folder that several runners sit in. When there is a runner at ~/actions-runner, the panel opens inside it and adding it is one click. Your choice is kept as a security-scoped bookmark, so the same folders can be read next time.
Repository-level runners are what ForgeLight understands. Organisation- and enterprise-level runners have no repository in their .runner file, so GitHub job detail is missing for them.
Do I need a GitHub token?
No. Runner status, the running job, its current step and its elapsed time all come from files on this Mac. A token adds what only GitHub knows — the workflow name, the pull request, and the step count that makes the menu bar ring show real progress.
Which token, with which permissions?
A fine-grained personal access token, owned by the account that owns the repositories, with access to the repositories your runners serve. Under Repository permissions: Actions: Read-only and Metadata: Read-only. Administration: Read-only is optional, used only by "Validate connection" to confirm a runner is registered. Add it under Settings → General → GitHub Tokens, then attach it to each runner under Settings → Runners. One token can serve every repository, or each can have its own.
Where does the token live?
In your macOS login Keychain, and nowhere else — never in preferences, logs or files, and never sent anywhere but api.github.com. ForgeLight does not read it back into the interface: a saved token can be replaced or removed, but not displayed.
When does ForgeLight talk to GitHub?
Only while one of your runners is running a job, and only if that runner has a token. A job starts: one fetch, then a refresh every 15 seconds. The job ends: exactly one more fetch, for the authoritative conclusion. Idle and offline runners are never polled. Without a token, ForgeLight makes no network requests at all.
How do I remove a token?
Settings → General → GitHub Tokens, then Remove beside the token. That deletes the Keychain item and detaches the token from every runner that used it.
How do I remove a runner, or the app?
To stop watching a runner, select it under Settings → Runners and remove it. Its thirty days of job history go with it. Removing a runner in ForgeLight does not touch the runner itself.
To remove the app, remove your tokens first if you would rather not leave them in the Keychain, then quit ForgeLight from its menu and drag it from Applications to the Trash. It runs no background agents and installs nothing outside itself, so nothing is left running. Its preferences and job history live in its sandbox container, ~/Library/Containers/me.shuaiyuan.forgelight.appstore, which you can delete too.
A runner shows "offline" but it is running
ForgeLight reads online from the runner's own Runner.Listener process, and busy from its Runner.Worker and the build tools that process spawned. If the listener has stopped — a service that failed to start, a runner still being configured — the runner reads as offline. Start it and the ring follows within a few seconds.
What does it need?
macOS 15 or later, and at least one self-hosted GitHub Actions runner installed on the same Mac. See Privacy for what the app reads and sends.
Anything else, write to support@shuaiyuan.me and a real person will write back.