localxpo for developers

Quick start

In the folder of an Expo app, link the project once. It signs you in to localxpo Cloud, picks the organization, creates the project in the dashboard and sets up your store credentials.

npx localxpo link
npx localxpo build -p android --profile preview      # build here, logs stream to the dashboard
npx localxpo build -p ios --profile production --submit   # build, then upload to TestFlight

link writes a small localxpo.json in the project with the dashboard URL and project id; every other command reads it. Profiles come from your existing eas.json, so nothing needs to change in the app.

Requirements

• Node.js 20 or newer, and the package manager of the project (npm, yarn, pnpm or bun).
• fastlane: brew install fastlane or gem install fastlane. A Gemfile with fastlane is used through bundle exec.
• Android: a JDK and the Android SDK (ANDROID_HOME set). Any macOS, Linux or Windows machine works.
• iOS: macOS with Xcode and CocoaPods.

Check a machine before the first build:

npx localxpo doctor     # Node, fastlane, JDK, Android SDK, Xcode, CocoaPods…

How it works

The CLI runs the whole build on your machine with fastlane, and reports to the dashboard over HTTPS: log lines in batches, steps, metrics and the result. The dashboard never runs builds and never receives your source code or binaries.

The Fastfile is written to a private temporary folder for each build, never into your project, and every value is passed as an environment variable. Key files are deleted when the build ends, including on Ctrl+C.

Commands

Run them with npx localxpo …, or install once with npm i -g localxpo (the short alias lxp works too).

Building

npx localxpo build -p ios --profile production
npx localxpo build -p android --profile preview --clean   # re-run expo prebuild --clean
npx localxpo build -p android -q                           # only errors and step headers

When a successful build already exists with the same native fingerprint, the CLI tells you; a build that only changes JavaScript can reuse it.

Submitting

npx localxpo submit                  # choose from a list
npx localxpo submit --latest         # newest build on this machine, no prompt
npx localxpo submit --build=<id>     # a specific build
npx localxpo submit --path app.aab   # any .ipa or .aab

Each upload is a submission with its own logs on the dashboard. Binaries never leave the machine, so a build is submitted from the machine that made it (or with --path). The Play track comes from submit.<profile>.android.track in eas.json (default internal).

Store credentials

link and credentials find what builds and uploads need, and only ask for what they can't find:

1. From Expo: with eas login or EXPO_TOKEN, Android upload keystores and the App Store Connect key ids are imported.
2. From this machine: eas.json submit settings, fastlane files, ~/.appstoreconnect/private_keys, Downloads and Desktop.
3. Created for you: a Google Play service account through gcloud, or guided downloads from Google Cloud and App Store Connect.
4. Checked: each key is verified with Apple or Google before it is saved.

Agents

Run the agent on each machine that should take builds started from the dashboard:

npx localxpo agent                      # serve this project
npx localxpo agent --dir ../other-app   # serve another project from the same machine
npx localxpo agent --list               # what this machine serves

It checks in every few seconds and runs one job at a time with the regular CLI, so logs, limits and credentials behave as in a terminal. A Mac builds iOS and Android; Linux and Windows build Android. A build whose machine stops responding for three minutes is marked failed, and resumes if the machine comes back.

CI and tokens

Create a token on CLI & tokens in the dashboard, then skip link in CI or on a headless Mac:

LOCALXPO_URL=https://your-dashboard LOCALXPO_TOKEN=lx_… npx localxpo build -p ios
LOCALXPO_NO_METRICS=1 npx localxpo build -p android    # turn machine metrics off

Environment variables

Variables are set per project and per environment (development, preview, production) on the dashboard, and injected by the CLI. The environment follows the profile's environment in eas.json, otherwise the profile name. Secret values are hidden in the dashboard and removed from logs.

Metrics and limits

During each build the CLI samples CPU, memory, memory pressure, swap, the heaviest build processes, power and free disk every 5 seconds, without sudo. The build page charts them per step, and the Machines page compares machines over 30 days.

Limits are set on the Machines page, per machine or as a default, with values recommended for each machine's hardware.

Logs and errors

• Every line is redacted on your machine first (keystore passwords, tokens, PEM blocks), then sent in batches every second.
• If the network drops, lines are queued and saved to ~/.localxpo/pending/; the next command (or localxpo sync) uploads them.
• About 30 known Xcode, Gradle, CocoaPods and store failures are recognised and shown with what went wrong and how to fix it.

REST API

Send a token with every request: Authorization: Bearer lx_…. Tokens are created on CLI & tokens; the browser session also works for GET requests.

curl -H "Authorization: Bearer $LOCALXPO_TOKEN" \
  "https://your-dashboard/api/v1/builds?projectId=…&status=success&limit=5"

Self-hosting

The dashboard is open source (MIT). Without configuration it uses an embedded Postgres stored in ./data; set DATABASE_URL to use your own.

pnpm install
pnpm dev                     # http://localhost:3000
pnpm build && pnpm start     # production

Prefer not to run a server? Create a free localxpo Cloud account; builds still run on your machines.