Self-hosted runner control plane

GitRun

Run your own GitHub Actions runners. Keep control of the machines, jobs, and security.

GitRun is the control room for runners on your own hardware. It manages Docker-based jobs, can route selected work to virtual machines, and brings runner health, secrets, security rules, recovery, and updates into one dashboard and CLI. And yes, there is a cat: the mascot is part of the project, while Kitty is the optional smart scheduler.

Open the repository Read the docs Releases

00What GitRun gives you

A practical toolkit for running GitHub Actions on your own infrastructure, without needing to build a Kubernetes platform around it.

Your machines, your runners

Connect a repository and run jobs on Linux hosts you administer, instead of relying only on hosted runners.

Security and recovery built in

Keep secrets scoped, apply runner policies, inspect health, and recover or roll back when an update goes wrong.

One control room

Use the desktop dashboard, terminal management console, or CLI. The scheduler keeps working when the window closes.

01Install on Debian or Ubuntu

AMD64 .deb. You do not clone the repo or compile Rust for the normal install. Docker is separate. The package is not ARM64. The snippet uses v1.8.21. A passing CI run is not the same thing as a signed release.

apt · v1.8.21

VERSION="v1.8.21"
ASSET="GitRun-${VERSION}-linux-x86_64-deb.deb"
curl -fL --proto '=https' --tlsv1.2 \
  "https://github.com/Vider06/GitRun/releases/download/${VERSION}/${ASSET}" \
  -o "${ASSET}"
sudo apt install "./${ASSET}"

Then gitrun setup or gitrun setup --terminal, connect a repository, and run gitrun doctor. From source: clone into /opt/gitrun-source and sudo ./scripts/install-server.sh.

02What actually runs

A dedicated Linux host, Docker with the API kept private, and a GitHub App or a PAT that can manage the repositories you connect. VM jobs need a hypervisor and images you supply. GitRun does not ship guest operating systems. Direct Docker-socket access for workflows stays off unless you turn it on, and turning it on hands the workflow host-level Docker.

Pools: Min and max runners, reconciled against busy agents and queued jobs.
Linux jobs: Managed Docker containers. Ephemeral lifecycle, recovery, CPU, memory and PID caps before more work is created.
Other machines: Logic Containers match job labels to local Docker or a named VM. KVM/libvirt, VirtualBox as fallback. Windows only on a VM endpoint you configured.
GitVault: Secrets at rest with AES-256-GCM. Global, group, and repository scopes.
GitSecureRun: Command and resource policy, workflow checks, a separate watchdog. Optional zizmor, only if you consent.
Updates: Ed25519 release manifests, SHA-256 on the artifact, a rollback journal written before anything is replaced.
Kitty: Optional statistical scheduler in gitrun-smart-scheduler. Forecasts demand. Not an LLM, not the default, and not in charge of the deterministic scheduler.
How you drive it: Tauri 2 dashboard, gitrun manage on a headless box, and the CLI. The scheduler keeps running when the window is closed.

03A closed API, not a host shell

Workflows call named Git*Run operations. Each one is checked against the runner identity, the GitHub job, and the repository policy. Complex shell stays an ordinary workflow step and still passes through GSR.

Operation	What it is for
GitVaultRun	Read, write, list, check, delete authorized secrets.
GitDockRun	Policy-checked container work, and mounts only when every gate agrees.
GitSaveRun	Save approved workflow files or fetch named logs.
GitInstallRun	Package install, removal, and update inside the runner, if policy allows.
GitReadRun / GitWriteRun	Approved paths only.
GitVerifyRun	SHA-256 of an approved file.
GitStatusRun	Ask GitRun how it is.
GitDispatchRun --plan	Optional Kitty dispatch plan, with an explicit GitHub fallback.

04Read it from the repository

These pages are the files on main. Nothing here is a second copy of the guide.

gitrun

gitrun setup
gitrun setup --terminal
gitrun connect OWNER/REPOSITORY
gitrun config
gitrun doctor
gitrun manage
gitrun dashboard
gitrun update --check
gitrun fast-stop OWNER/REPOSITORY RUN_ID --yes
gitrun rollback BACKUP_PATH

Where GitHub stops

1
The repository
Code, issues, pull requests, releases, Actions workflows. The wiki, once published, lives there too.
2
A job needs a runner
A workflow describes work. GitHub Actions hands the job to a machine that has the runner agent, chosen by labels.
3
That machine can be yours
GitHub can lend a hosted runner. A self-hosted one is a host you administer. GitRun is the control plane for that host. It is not GitHub, and it does not need Kubernetes.