Starting Loop: Build

This website covers 2 versions of Loop: Loop-main and FreeAPS.  Loop-main is also referred to as Loop 3 and is the most up-to-date version.  FreeAPS is based upon Loop 2 and is not under current development.  We recommend that you build Loop-main because it includes feature enhancements and safety improvements that are not found in FreeAPS.

If you’d like to build Loop-main, then you’ll need an iPhone capable of running iOS 15.1 or higher, but we recommend iOS 16.  If you have a Mac that can operate macOS 12.5 or higher, then the easiest way for you to build Loop-main is to use the Build-Select Script.  If you don’t have a Mac that can handle macOS 12.5 or higher or you’re a PC user, then there’s another build method that was created just for you – the Browser Build.

If thinking about FreeAPS, be warned that FreeAPS sunset is approaching

  • There will be limited support for FreeAPS in the future
  • There is the chance that the next iOS or Xcode update could “break” FreeAPS and you would need to migrate to another Loop branch or fork. 
  • Please build Loop-main

To build FreeAPS, you’ll need an iPhone capable of running iOS 14 or higher, and a Mac that can operate macOS 10.15.4 and Xcode 12.  The easiest way to verify that your iOS, Xcode, and macOS are compatible is this site and scroll down to the Version Comparison Table.   The easiest way for you to build FreeAPS is to use the Build-Select Script.  See the Mac Build section below.

Before you start your build, please complete the items on the Checklist.  Make sure to pay particular attention to the Cautions and Future Tasks sections that come after the Checklist. To be successful – you must not skip them.


  • Check that your iPhone or iPod iOS is at the level needed to run the version you want to use.
  • Check that you have a compatible pump and CGM
  • Check that your radio-link is charged or has batteries (RileyLink, OrangeLink, or EmaLink).  A radio-link device is required for all pumps except for DASH
  • Check that your Apple Developer program subscription is valid and visit the site to make sure no new terms or conditions are pending acceptance
  • Check that you have a plan to deal with data for yourself, your doctor, or perhaps a caregiver
    • If this is for a child, consider how you are going to handle interactions with the school nurse and when/if/what you need to add to the 504 plan
    • Make sure you are in a position to keep the school from taking away the RileyLink or Phone from your child

There are now two different build methods – Mac Build and Browser Build.  Your next steps depend upon which method you’re using.

Mac Build

  • Check that your Mac OS is compatible with the version of Loop that you’d like to build (see details above).
  • Check that your version of Xcode is consistent with the iOS on your phone or install the correct version of Xcode
  • Plug in your phone and use the Build-Select Script to build the version you have selected
    • It may take a long time, but Xcode will always finish with a “Build Succeeded” or “Build Failed” message
    • If it failed – read the message – it may be as simple as your phone being locked and needing to be unlocked
    • If it really failed, read the How To Ask For Build Help page
    • If your build succeeded, simply unplug your phone
    • You will get a message that Xcode lost connection with your phone – that is correct

Browser Build

  • You’ll need a GitHub account in addition to the Check List requirements above
  • Instructions for Browser Build are in LoopDocs
  • The disadvantages of this method are that you must rebuild every 90 days (which is much easier than the initial build) and you won’t be able to customize your app.

For Both Build Methods

  • Go to LoopDocs Setup App for instructions on how to set up your radio-link, pump, and CGM
    • These documents advise not to add Dexcom Share credentials when adding your CGM
    • Follow that suggestion – in fact, if you added your share credentials under the Transmitter setup screen, go back and delete your CGM and add the CGM back using just the Transmitter ID
  • After finishing the Set up App steps, continue to the LoopDocs Operate section and review the instructions on using your App
  • Leave Loop “Open” until you have adjusted your settings with Loop making predictions and suggestions, but not automatically enacting any insulin dosing recommendations


  • Your previous settings are probably wrong for Loop
    • Your settings were fine for manual pumping and manually correcting every few hours
    • Loop uses a model for carbs and insulin that updates once every 5 minutes based on your CGM readings
    • Start with Loop “Open” and check your settings until you have them close to your desired results
    • It is not uncommon to need a higher number for your ISF with Loop
  • Commit to checking into either FaceBook or Zulipchat at least weekly to look for safety-related warnings. If you are not going to check in weekly, at a bare minimum, sign up for the Loop and Learn Newsletter, and read it when it shows up in your inbox.
  • Don’t be afraid to switch between closed-loop and open-loop often as you get your settings sorted out.
  • Overnights are often the first part of the day that people choose to run Closed Loop because, with proper settings, Loop will decrease or prevent low blood sugars and have you waking up in your target range. But, jump in the pool slowly.
  • You can use Loop as simply a Pump Controller (MMT) or PDM (Omnipod) to manually enter bolus amounts. When you run Loop “Open” it will make bolus recommendations that you can decide to manually administer.  As you grow comfortable with those recommendations, you can start to run a “Closed” Loop and let Loop do the adjustments to your insulin dosing. Don’t think it is a race to be full-time Looping. You can Open and Close the Loop, watch, adjust, and learn.
  • And, always, if you have a dodgy CGM, Open Loop until stable CGM data is available. If the CGM is giving you bad data, Loop might make bad predictions. This is not a good idea. For example, if you restart your CGM sensors to extend their life, you know that the final days of that extended life can be dodgy.  While you are starting on Loop, you may decide not to do extended sensor sessions until you are confident of your new settings.

 Future Tasks

  • Data for Doctor:  Make a plan for how you will share your data with your doctors! The night before the appointment is too late.
  • Updates!  Make sure your Profile expiration date is on your calendar along with your Developer renewal date
  • We recommend that all Loopers rebuild every 90 days, but for Browser Builders, it is an absolute requirement.


Please let us know with a post in Loop and Learn that you followed this Checklist and made it into Looping.  OR, if you don’t want to post in public, use the feedback form on this page to let us know.

We are all volunteers. We’d like to know if our hard work and passion for putting together this information has helped people, or not.

Skip to content