# kinhin > Your Mac is your CI and your repo is your video studio. Autoscaling ephemeral runners for GitHub, GitLab, Gitea and Forgejo, plus narrated launch videos built from a config. ## Get started - [Why kinhin](https://kinhin.dev/guide/why-kinhin.md): Self-hosted CI runners do one job at a time. kinhin exists to give your Mac real concurrency. - [Compare to other CI](https://kinhin.dev/guide/compare.md): What other tools do, what kinhin does, and what kinhin is missing. - [Quick start](https://kinhin.dev/guide/quick-start.md): Kinhin turns your Apple Silicon Mac into an autoscaling fleet of ephemeral self-hosted CI runners. This page gets you from zero to a working fleet. New here? Read why kinhin exists. - [Install & updates](https://kinhin.dev/guide/install.md): The install script in detail, and update checks. - [Forge support](https://kinhin.dev/guide/forges.md): Which CI platforms kinhin serves, how to connect each one, and how to serve many accounts from one fleet. - [Configuration](https://kinhin.dev/guide/config.md): ~/Library/Application Support/Kinhin/config.yaml — write the commented starter file with kinhin config init. Key fields: ## Run your fleet - [Runtimes & routing](https://kinhin.dev/guide/runtimes.md): Where jobs run (Tart VMs, apple/container microVMs, Docker containers, or directly on your Mac) and how one fleet routes each job between them. - [How scaling works](https://kinhin.dev/guide/scaling.md): The capacity cap, the scaling loop, job density, and how kinhin recovers from restarts. - [Toolchains & shared cache](https://kinhin.dev/guide/toolchains.md): How to get Go, Node, Xcode, Flutter and friends onto kinhin runners, and how to cache their downloads. - [Requeue and skip queued jobs](https://kinhin.dev/guide/requeue-skip.md): The Fleet tab now lets you re-queue or drop the fleet's queued jobs, per forge, from the Requeue / skip queued row (one button per attached forge). - [The healing agent](https://kinhin.dev/guide/healing.md): kinhin watches its own fleet for problems and fixes the ones it safely can. A warm VM that was deleted behind its back, a toolchain cache filling the disk, an account that dropped off for a minute: these are fixed on their own. Anything destructive or slow (pruning images, reinstalling a runtime) waits for you to approve it. Anything only you can do (a new token, an image bake) is shown with the exact command. - [Telemetry (OpenTelemetry)](https://kinhin.dev/guide/telemetry.md): kinhin can export metrics, traces and logs about the fleet and the jobs it runs over OTLP, and serve the metrics on a local Prometheus endpoint. It is off by default: until you turn it on, kinhin starts no exporter, opens no port and sends nothing anywhere. - [Alerts (webhooks)](https://kinhin.dev/guide/alerts.md): kinhin can push a message to one or more webhooks when something is wrong, so a closed menu bar app or a headless host still reaches you. The macOS notification the app posts is separate and unchanged. - [Test workflows locally](https://kinhin.dev/guide/workflow-testing.md): kinhin workflow test runs a repository's GitHub Actions workflow scripts on your Mac before you push. It is a host-only convenience tool: it does not start the fleet, a VM, the daemon, or read kinhin's config or forge credentials. The Fleet tab also has Test Workflow…, which opens the same runner in a sheet after you choose a workflow file in Finder. - [Benchmarks](https://kinhin.dev/guide/benchmarks.md): kinhin bench measures, on this Mac, how fast every runtime boots, how fast representative workloads run inside them, how fast every toolchain in the catalog installs and builds, and how long a demo video takes to render. It writes a machine-readable report and removes everything it created. The same runs are available in the app under Advanced → Benchmarks. ## Mobile releases - [Tutorial: first build](https://kinhin.dev/guide/mobile-fastlane-tutorial.md): This walks through a first release from a clean start: scaffold the project, set up the credentials once, run a beta lane by hand, then run it from CI. It takes about an hour the first time, most of it waiting on Apple and Google. - [Reference](https://kinhin.dev/guide/mobile-fastlane.md): This is opt-in. kinhin's runners, configuration and commands work exactly as before unless you run kinhin mobile init in a project. Running it only adds files to that project: fastlane lanes, a Gemfile, and a CI workflow. kinhin's own config is not read or changed by it. - [Credentials](https://kinhin.dev/guide/mobile-credentials.md): Every secret the release workflow reads, where to get it, and what each one is for. None of them are stored by kinhin. Store them as repository secrets (Settings, then Secrets and variables, then Actions). The workflow maps them into the lanes, and each lane checks for the ones it needs before any store call. - [Store screenshots](https://kinhin.dev/guide/mobile-screenshots.md): kinhin mobile init adds a screenshots lane to the iOS and Android projects. It captures localized screenshots from UI tests (iOS: snapshot; Android: screengrab), can frame them with frameit, and can upload them to the stores. Upload is off unless you turn it on. This page covers setup, the folder layout, every setting you can change, and what has been verified. - [Troubleshooting](https://kinhin.dev/guide/mobile-fastlane-troubleshooting.md): The failures we have hit while building and testing the integration, with the cause and the fix. Each heading is the text of the error, so search for it. ## Hardware & hosting - [Hardware & sizing](https://kinhin.dev/guide/hardware.md): What your Mac needs to run kinhin, and how to size CPU, memory, and storage for the fleet you want. - [Running on a rented Mac](https://kinhin.dev/guide/rented-mac.md): Run a kinhin fleet on a Mac you rent by the month instead of one on your desk: a colocated Mac mini or a bare-metal cloud Mac. This is also how a team or consultancy can run CI for someone else: one dedicated Mac per customer, their own forge token, no shared hardware. ## Security - [Security](https://kinhin.dev/guide/security.md): What kinhin protects, what it leaves to you, and the settings to turn on if your jobs can include code you don't fully trust (fork PRs, outside contributors). - [Open-source projects](https://kinhin.dev/guide/open-source.md): How to use kinhin for a public repository without letting a stranger's pull request run code on your Mac. ## Product videos - [Add videos to your project](https://kinhin.dev/guide/videos-for-your-project.md): Make a narrated launch video, a feature clip or a README GIF for your own product. The video is a config file in your repository: scenes, a voice-over, music, captions and a theme. One command turns it into an MP4, a WebM, a poster, a GIF and a caption file. Everything runs in a container, on open-source tools, with no accounts. - [Video config reference](https://kinhin.dev/guide/video-config.md): Everything a video file can say. Start with the first video if you have not built one yet. Each video is one YAML or JSON file in .kinhin/videos/; the fields below go at its top level. - [Recordings of your product](https://kinhin.dev/guide/video-adapters.md): A device, terminal or split scene shows recordings of your product. You do not need recording tools to use a clip you already have. This page covers the adapter folder that holds the recordings, the claims check that keeps the video honest, and the optional web recorder. - [Video troubleshooting](https://kinhin.dev/guide/video-troubleshooting.md): The messages a video build is most likely to print, and what to do. Find the text your build printed in the left column. - [Video gallery](https://kinhin.dev/guide/video-gallery.md): Every video below is built from a JSON file in video/script/ with one command, in a container, from committed sources. Each picture is a frame from each scene of the real build. To make one of your own, copy a file into your repository's .kinhin/videos/ and run kinhin video build (see Add videos to your project). video/scripts/gallery.mjs rebuilds all of this page and writes a page where you can play the videos. - [Marketing video in CI](https://kinhin.dev/guide/ci-video.md): The video suite (Add videos to your project) can build a launch video, social cuts and a preview of video changes in GitHub Actions, from committed sources, with no secrets. It is off by default: a repository that does not opt in gets no jobs, no cost and no new permissions. ## Help - [Troubleshooting](https://kinhin.dev/guide/troubleshooting.md): Start with kinhin heal: the healing agent fixes many of the problems below on its own, lists the fixes waiting for your approval, and says what only you can do. - [Beta roadmap](https://kinhin.dev/guide/beta-roadmap.md): What is supported today, and the milestones between the current beta and the v0.1.0 release. - [Support & sponsors](https://kinhin.dev/guide/support.md): kinhin is free, Apache-2.0, and built by one developer, with no ads and no telemetry unless you opt in and point it at your own OpenTelemetry server (Telemetry). Donations and sponsors pay for CI, code signing, test hardware and development time. - [Who uses kinhin](https://kinhin.dev/guide/used-by.md): A short, hand-picked list of companies and projects that run their CI on kinhin. It appears on the website. ## Reference - [CLI commands](https://kinhin.dev/cli/commands.md): kinhin — autoscaling CI runners on your Mac. Tart VMs run macOS jobs; apple/container, Docker or Tart Linux VMs run Linux jobs. Forges: GitHub Actions, GitLab CI/CD, Gitea, Forgejo (Buildkite, Azure, Bitbucket planned). - [AI agents & MCP](https://kinhin.dev/guide/agents.md): Two ways AI agents meet kinhin: operating a fleet on someone's Mac, and contributing to the kinhin repository itself. Both surfaces are deliberate: every read command has a machine-readable document, the CLI speaks MCP, and the skills under skills/ teach an agent the workflows around the commands. - [Architecture](https://kinhin.dev/guide/architecture.md): How the Swift package is laid out, what the tests cover, and what CI runs. - [Overview](https://kinhin.dev/guide/forges/overview.md): What kinhin assumes about each forge's API, checked against the forge's own documentation. - [GitHub](https://kinhin.dev/guide/forges/github.md): How kinhin talks to GitHub Actions, and how that compares with GitHub's current REST API docs. - [Gitea & Forgejo](https://kinhin.dev/guide/forges/gitea.md): How kinhin talks to Gitea Actions and Forgejo Actions, and how that compares with their current API specs. Forgejo is served by the same client (GiteaClient); this page notes where the two diverge. - [GitLab](https://kinhin.dev/guide/forges/gitlab.md): How kinhin talks to GitLab CI, and how that compares with GitLab's current REST API docs. - [Buildkite (planned)](https://kinhin.dev/guide/forges/buildkite.md): How kinhin talks to Buildkite, and how that compares with Buildkite's current REST API docs. - [Azure DevOps (experimental)](https://kinhin.dev/guide/forges/azuredevops.md): How kinhin talks to Azure Pipelines agent pools, and how that compares with Microsoft's current REST API docs. - [Bitbucket (planned)](https://kinhin.dev/guide/forges/bitbucket.md): How kinhin talks to Bitbucket Pipelines runners, and how that compares with Atlassian's published API spec. ## Contributing - [Contributing](https://kinhin.dev/guide/contributing.md): kinhin is built by one developer, and bug reports, feature requests and pull requests are welcome on GitHub. Not writing code? You can also add your project to Who uses kinhin or support the project. - [End-to-end testing](https://kinhin.dev/guide/e2e-testing.md): swift test runs about 3,400 tests against fakes (FakeTart, FakeSSH, FakeGitea, ...) in about a minute and a half with --parallel (warm build) and no VMs and no network. That keeps the suite fast, but it can only prove kinhin agrees with its own model of a forge or a runner. The end-to-end (e2e) suite in Tests/E2E checks the model against the real thing: a real forge in a container, a real kinhin daemon, a real runner image, and a job that really runs inside a guest. - [Setting up the hosted e2e lanes](https://kinhin.dev/guide/e2e-hosted-forges.md): How to create the throwaway Buildkite, Azure DevOps and Bitbucket accounts the end-to-end suite needs, and wire them to CI. Each lane is gated: with its secrets unset it is skipped silently, so you can turn them on one at a time. - [Making kinhin's demo video](https://kinhin.dev/guide/making-a-video.md): How kinhin makes its own launch video and demos: a debug build replays a scripted fleet (jobs arrive, instances clone, boot, run and are deleted, one fails and its retry passes) while you screen-record the real app. This page is for people working on kinhin. To make videos of your own product, see Add videos to your project: the project file, scene types, adapters, captions, music and the .kinhin/videos/ folder are documented there. - [Debugging races (TSan)](https://kinhin.dev/guide/debugging-races.md): For contributors: how to run kinhin's test suite under ThreadSanitizer (scripts/tsan.sh) and read the result. - [Cutting a release](https://kinhin.dev/guide/releasing.md): How a maintainer builds, signs, notarizes and publishes a kinhin release — locally as a rehearsal, then from a tag for real. ## Blog - [Introducing the kinhin beta](https://kinhin.dev/blog/introducing-kinhin-beta.md): The first public beta of kinhin, the mindful CI for your Mac. What works today, what doesn't, who should try it now, and how it was tested. - [Beta 7: a redesigned app, storage on any volume, and several alert webhooks](https://kinhin.dev/blog/beta-7.md): The seventh public beta of kinhin, the mindful CI for your Mac. What is new in beta 7, what changes when you upgrade, what has been run, what has not, and where I need your help. - [Beta 6: alerts that reach you, a Tart panic fix, and one engine per Mac](https://kinhin.dev/blog/beta-6.md): The sixth public beta of kinhin, the mindful CI for your Mac. What is new in beta 6, what changes when you upgrade, what has been run, what has not, and where I need your help. - [Beta 5: Apple container pools, Docker inside containers, and x86_64 runners](https://kinhin.dev/blog/beta-5.md): The fifth public beta of kinhin, the mindful CI for your Mac. What is new in beta 5, what changes when you upgrade, what has been run, what has not, and where I need your help. - [Beta 4: telemetry you opt into, macOS 27 images, and fixes from your installs](https://kinhin.dev/blog/beta-4.md): The fourth public beta of kinhin, the mindful CI for your Mac. What is new in beta 4, what changes when you upgrade, what has been run, what has not, and where I need your help. - [Beta 3: updates that install themselves, restarts that leave your jobs alone, and seven new languages](https://kinhin.dev/blog/beta-3.md): The third public beta of kinhin, the mindful CI for your Mac. What is new in beta 3, what has been run, what has not, and where I need your help. - [Beta 2: a fleet that heals itself, warm pools per image, and videos from your repo](https://kinhin.dev/blog/beta-2.md): The second public beta of kinhin, the mindful CI for your Mac. What is new in beta 2, what has been run, what has not, and where I need your help. ## Optional - [Blog](https://kinhin.dev/blog.md): News, release notes and behind the scenes from kinhin. - [Alternatives to Orchard for CI on a Mac](https://kinhin.dev/alternatives-to-orchard-for-ci-on-a-mac.md): Orchard orchestrates Tart VMs across Macs but is not a CI integration. Here are the tools that run CI runners on a Mac, and when to pick each. - [How many macOS VMs can run at once?](https://kinhin.dev/how-many-macos-vms-can-run-at-once.md): Apple's licence and Virtualization framework allow two macOS guest VMs on one Mac at a time. Here is how kinhin runs more macOS jobs than that. - [How to autoscale GitHub Actions runners on a Mac](https://kinhin.dev/how-to-autoscale-github-actions-runners-on-a-mac.md): kinhin starts GitHub Actions runners on your Mac as jobs queue, up to a cap set by the Mac's cores, memory and free disk, then deletes them. - [How to generate localized app store screenshots](https://kinhin.dev/how-to-generate-localized-app-store-screenshots.md): List the languages once and fastlane captures your screenshots in each one, in its own folder. Works for iOS with snapshot and Android with screengrab. - [How to make a product launch video from code](https://kinhin.dev/how-to-make-a-product-launch-video-from-code.md): Keep a launch video's script in your repo as YAML. kinhin renders narration, captions and music into an MP4, WebM, poster and GIF on each build. - [How to run fastlane screenshots in CI on a Mac](https://kinhin.dev/how-to-run-fastlane-screenshots-in-ci-on-a-mac.md): Run the fastlane screenshots lane on a kinhin runner and keep the PNGs as a CI artifact, since the VM is deleted when the job ends. - [How to run Gitea or Forgejo Actions on a Mac](https://kinhin.dev/how-to-run-gitea-or-forgejo-actions-on-a-mac.md): Run Gitea or Forgejo Actions jobs on your own Apple Silicon Mac with kinhin, which starts a VM for each job and deletes it afterwards. - [How to run GitHub Actions on a self-hosted Mac](https://kinhin.dev/how-to-run-github-actions-on-a-self-hosted-mac.md): Run GitHub Actions jobs on your own Apple Silicon Mac. kinhin starts a fresh VM for each queued job and deletes it when the job ends. - [How to run GitLab CI jobs on a Mac](https://kinhin.dev/how-to-run-gitlab-ci-jobs-on-a-mac.md): Run GitLab CI jobs that need macOS on your own Apple Silicon Mac. kinhin creates a runner per waiting job and deletes it after the job. - [How to take App Store screenshots automatically](https://kinhin.dev/how-to-take-app-store-screenshots-automatically.md): Write UI tests once, then let fastlane capture your App Store screenshots from them. kinhin adds the lane, the settings and the sample tests. - [Self-hosted alternative to GitHub-hosted macOS runners](https://kinhin.dev/self-hosted-alternative-to-github-hosted-macos-runners.md): Run GitHub Actions macOS jobs on a Mac you own. Each job gets a fresh VM that is deleted afterwards. kinhin is free and open source; you supply the Mac. - [Architecture: screenshots](https://kinhin.dev/guide/architecture-screenshots.md): How kinhin mobile init sets up store screenshots, what the lane does on each platform, and how the screenshots leave the VM. This page is a companion to the architecture overview; the setup guide is Store screenshots with fastlane. - [Architecture: videos](https://kinhin.dev/guide/architecture-videos.md): How kinhin video turns a repository's video project into an MP4, and how the marketing video runs in CI. This page is a companion to the architecture overview; the product-facing guides are Videos for your project, Making kinhin's demo video and Marketing video in CI.