Get started with Hangar

Hangar turns a Mac you own into a private Expo build server. This guide takes you from npm install to a downloadable .ipa — install the CLI, point it at your server, log in, and build.

Requirements

Before you start, make sure you have:

• An Expo (React Native) project where eas build --local already succeeds.
• Your existing eas.json with the build profiles you use (e.g. production, preview).
• Node.js 22+ on the machine you'll run the CLI from.
• A running Hangar server URL and an account on it (ask your operator, or set one up yourself).

Install the CLI

The CLI is published on npm. Install it globally:

$ npm i -g @chronsyn/hangar-cli

Verify the install:

$ hangar help
# prints usage and the full command list

Quickstart

From the root of your Expo project, four steps get you to an artifact.

1. Point the CLI at your server

   Tell the CLI where your Hangar server lives. This is the URL your operator gave you (or your own deployment). You can also pass --server <url> per command, or set HANGAR_SERVER.

   bashCopy

   $ hangar config set defaultServer https://build.your-team.dev

2. Log in

   Authentication uses the browser-based device flow. The CLI prints a verification URL and a short code — open the URL, sign in, and approve the code. No password is ever typed in the terminal.

   bashCopy

   $ hangar login
   → Open https://build.your-team.dev/oauth/device and enter code: WXYZ-1234
   ✓ Authorized — logged in to build.your-team.dev

3. Start a build

   Pick a platform and one of your existing EAS profiles. The CLI bundles your working tree, encrypts it, and streams it to the server. Add --wait to poll status until the build finishes.

   bashCopy

   $ hangar build --platform ios --profile production --wait
   ↑ encrypting & uploading bundle… done (3.1s)
   → build a3f9c12 submitted on mac-mini-01
   • status: queued → running…

4. Track, then download

   The CLI prints status transitions to completion. For streaming logs and per-step progress, open the build in the dashboard. When it passes, grab the artifact.

   bashCopy

   ✓ status: succeeded 3m 29s
   → artifact ready: flightdeck-ios-a3f9c12.ipa
   
   $ hangar artifacts download a3f9c12

Setting up the server

Everything above is the developer flow — connecting to a server that's already running. This section is for the operator: the person who turns a Mac they own into the Hangar build server everyone else points their CLI at.

What this section will cover:

CLI commands

The commands you'll reach for most often. Flags shown are the common ones.

hangar build

Bundle the working tree, encrypt it, and run a build on the server. By default the CLI submits and returns; add --wait to poll status until the build finishes.

$ hangar build --platform ios|android \
              --profile production \
              --wait           # poll status to completion

hangar builds

List recent builds and their status. Also: builds view <id>, builds cancel <id>, builds delete <id> [--yes].

$ hangar builds list
ID        PLATFORM  PROFILE      STATUS    DURATION
a3f9c12   ios       production   building  —
7b1e0a4   ios       production   passed    3m 38s
c0d4e91   android   preview      passed    2m 02s

hangar artifacts download

Download a build artifact by build ID. Optional --output <path> and --kind <ipa|apk|aab|ios-simulator>.

$ hangar artifacts download a3f9c12
$ hangar artifacts download a3f9c12 --output ./build.ipa

The dashboard

The dashboard covers the same core actions as the CLI — and adds the things the terminal can't show. Sign in at your server URL to:

• Start a build by picking a platform and EAS profile.
• Watch each build step and stream logs in real time, with a live progress bar.
• Download .ipa, .aab, and simulator artifacts — including over-the-air iOS internal distribution when your deployment has public TLS.
• Manage membership: toggle open registration on/off and disable any account. The operator holds the superadmin role.

Scope & limits

Hangar handles the build step only. It's deliberate, and it keeps the tool small and trustworthy. Hangar does not replace EAS for:

• Credential provisioning
• App-store submission (eas submit)
• OTA updates (eas update)

It's single-host (one Mac) and self-hosted — there is no hosted-cloud mode. The honest, stronger message: self-host the build step, and keep using Expo for the rest.

FAQ

Does my source leave my hardware?

Not in the clear. The CLI encrypts the bundle before it hits the network and it stays encrypted at rest. Decryption happens inside the builder process on your Mac — the machine you own and operate.

Do I need to change my Expo config?

No. Hangar uses your existing eas.json profiles and Expo config. If eas build --local works in your checkout, Hangar works.

Can a team share one server?

Yes — one Mac serves the whole team, but each account is private. Teammates self-register (the operator can open or close registration at any time), and the operator can disable any account. Builds and artifacts are visible only to the user who ran them — the single superadmin operator can see all. There's no shared project view: two people building the same app keep separate, private histories.

What does it cost?

Hangar is free and will be open source soon. Your only cost is the Mac you run it on — which, for most teams, is hardware they already own.