kbf

Early development open source, Apache 2.0

Remote builds on your own machines.

kbf is a remote execution build farm for Buck2 and Bazel. Your build tool sends actions to one address; kbf runs them on your workers and keeps every result in a shared, content-addressed cache.

Install published with the first release

$ curl -fsSL https://kbf.dev/install.sh | sudo sh

The script verifies what it downloads and starts nothing. Other channels are on the install page.

Quick start Watch a real build

Get started

From a host to a remote build in three steps

  1. Install the installer

    kbf-installer installs and verifies kbf, then takes update orders. Installing starts nothing. specified

    $ curl -fsSL https://kbf.dev/install.sh | sudo sh

  2. Set up a mode

    One host can run everything; a farm splits the roles. specified

    $ sudo kbf-installer setup --mode=all-in-one

  3. Point Buck2 at it

    In your .buckconfig, send actions and cache reads to the frontend. works today

    [buck2_re_client]
  engine_address = grpc://FRONTEND:8980
  action_cache_address = grpc://FRONTEND:8980
  cas_address = grpc://FRONTEND:8980

The quick start has every flag and what is built today.

Demo

A real build, replayed

A person writes a target, runs the build, and watches the farm work. This is a recorded run of the farm building a slice of a real project, replayed: the terminal is what the build tool printed, and the picture is what the farm did in the same window. Time is compressed.

Terminal


        

      


      

        
        
        
        
      


      

        

          

          
Amber dots: a lease going from the frontend to a daemon. Blue dots: an action answered from the cache, or a daemon sending outputs to storage. Red: a remote action that failed. Dots show direction, not size; the counters are exact.

        

        
    
          
  • 0:00build time
    • 
          
  • 0actions Buck2 is waiting on
    • 
          
  • 0running on daemons
    • 
          
  • 0answered from the cache
    • 
          
  • 0remote runs finished
    • 
          
  • 0leases granted
    • 
          
  • 0remote runs failed
    • 
        

      

      
This demo replays a recording with a script, and scripts are off. The totals are below.


      

        
The recording: one cold build of a slice of a real project on a test farm of 2 daemons, started with buck2 build from a list of targets. The build client reported  commands:  answered from the cache (%),  run remotely,  local. It took  and ended :  remote actions failed, and the terminal shows what the build client printed for them.

        
What was kept: the terminal text is the build client's own output at its real relative times, with host names, addresses, paths, ids and digests removed. The farm side is the frontend's lease log,  leases, with the daemons renamed daemon-1 and up. Cache hits are grouped into  ms steps, because the recording has over a thousand and the picture draws one flash per step. The data is in the repository.

      

    

  






  

    
Why we built it

    
A farm for the work that needs real machines

    
We wanted one open farm that runs the whole build, including the tests that need a real Mac, a real display or a real device, and that keeps what happened.

    
    
      
  • 
        
    UI, Mac and iOS tests on real machines
    
        
    These tests need a logged-in macOS session, Xcode and, for iOS, a device on a cable. kbf runs actions on Mac nodes as plain processes with their process tree, memory and network watched.
    
        
    Mac daemon: works todayiOS devices: specified
    
      
    • 
      
  • 
        
    Utilization you do not tune by hand
    
        
    In our experience, fitting actions to machines is hard to configure. kbf has no per-action reservations: it admits actions by CPUs and a memory ladder, and sizes cgroups from what it measures.
    
        
    works today
    
      
    • 
      
  • 
        
    Open source, all of it
    
        
    Some other farms are not completely open source. kbf is licensed under the Apache License 2.0.
    
        
    works today
    
      
    • 
      
  • 
        
    Every build kept, and a way to read it
    
        
    kbf records the attempts and cache hits of each invocation. We are designing a UI to explore all logs and metrics, and an API that an AI agent can use to fetch results.
    
        
    build history: works todaylogs and metrics UI: specifiedAI fetch: specified
    
      
    • 
    

    
Read the story: from one laptop to a farm

  






  

    
Architecture and the rest

    
Four parts, one binary

    
    
      
  • frontend
    The one address clients, daemons and storage nodes know. Serves REAPI and schedules actions. Its state lives in a Postgres database you provide.
    • 
      
  • storage
    The content-addressable store and action cache: an SSD hot tier, flushed in the background to an object store.
    • 
      
  • daemon
    The worker. It fetches inputs, runs each action in isolation and uploads outputs. Linux and macOS.
    • 
      
  • all-in-one
    The parts in one process, for a single machine or a first try.
    • 
    

    
A host takes a role with --mode: frontend, storage, daemon, storage-and-daemon or all-in-one. Read the architecture, every setting and how a farm updates itself.

    
Status. Early development. The project is design-first: interfaces and tests land before features, and nothing here is ready for production use yet. Expect breaking changes. Each step on these pages says whether it works today or is specified.