Using OpenOTA

Introduction

OpenOTA lets you ship JavaScript changes to a React Native app instantly — no app store review, no waiting days for a rollout. You build a bundle, push it to your own server (or OpenOTA Cloud), and every installed app checks in, downloads, verifies, and applies the update on its own. If something goes wrong, rollback is instant and happens entirely on-device.

It's the same idea as CodePush or Expo Updates, with two differences that shape everything else in these docs: you own the server (self-host it, or use the hosted Cloud — same code, your choice), and the device never trusts the server blindly — the native runtime re-verifies every bundle's checksum itself before running it.

How it works

Your RN app (SDK)   ──check/download──▶   OpenOTA Server
      ▲                                        │
      │ verify + apply                         ├──▶ Postgres  (metadata)
      │                                        └──▶ Storage   (bundle .zip)
 openota CLI  ─────────release────────────────▶

1. You release. openota release bundles your JS (via Metro), computes a SHA-256 checksum, and uploads it to your server.
2. The server stores it two ways. Postgres holds only metadata (which version is "active" per environment); the actual bundle bytes go to your storage backend. Kept separate on purpose — see What you need.
3. A device checks in. OTA.check() asks the server "what's active for my platform + environment?" and compares it to the device's current version.
4. It downloads and verifies independently. The native (Kotlin/Swift) runtime re-computes the checksum itself before ever running the new code — the server's word is never enough on its own.
5. Rollback is instant and local. The previous bundle stays on-device, so rolling back is a pointer swap, not a re-download.

Core concepts

What you need

If you're using OpenOTA Cloud, all of this is already running — skip straight to Quickstart. If you're self-hosting, here's exactly what's required vs. optional.

No Redis, no message queue, no separate auth provider — deliberately minimal.

Quickstart

npm install -D @openota/cli

npx openota init --server-url https://YOUR-SERVER/api/v1 --runtime-version 1.0.0
npx openota doctor
npx openota release --version 1.0.1 --platform android

openota init detects your package manager (npm, yarn, or pnpm) and automatically installs @openota/sdk, @openota/native-android, and every native peer dependency the SDK needs — nothing to install by hand. Pass --skip-install to opt out. If a dependency ever goes missing later, npx openota doctor --fix repairs it the same way.

Full native wiring (Android/iOS) and SDK integration walkthrough lives in docs/GETTING_STARTED.md.

Self-hosted vs. Cloud

Both modes run from the exact same server binary and coexist — turning on Cloud never breaks the self-hosted flat routes. Full reference: docs/CLOUD.md.

CLI reference

SDK config (OTA.configure)

Setting projectId also makes the SDK send an anonymous, auto-generated device ID on every check/download, and report install/rollback outcomes automatically — that's what populates the dashboard's Devices and Analytics pages. Nothing extra to wire up.

Native dependencies

@openota/sdk is a thin JS layer over a few native modules. openota init installs these automatically (see Quickstart above) — but every one of them still needs a real native rebuild before the SDK will work, not just a JS reload.

# Already installed for you by `openota init` — only needed if you're adding these manually
npm install react-native-mmkv react-native-nitro-modules \
  react-native-fs react-native-zip-archive \
  react-native-quick-crypto react-native-quick-base64

# iOS — required after installing or upgrading any of the above
cd ios && bundle exec pod install && cd ..

# Android — autolinking picks these up automatically, but only on a full rebuild
cd android && ./gradlew clean && cd ..

npx react-native run-ios   # or run-android

Forgetting the native rebuild is the single most common integration mistake — it surfaces as a vague JS error like Cannot read property 'otaStorage' of undefined the moment OTA.configure() or OTA.sync() runs, since the native module the SDK depends on was never linked into the app binary. npx openota doctor checks for this.

Remote config (optional)

Separate from OTA bundles entirely — a per-(project, platform) JSON value your app can fetch at runtime and react to however you like. Editable from the dashboard's Apps page, no new release required to change it.

GET  /projects/:projectId/apps/:platform/config   # public, no auth — same as check/download
PUT  /projects/:projectId/apps/:platform          # session-authed, dashboard/API only
     body: { "remoteConfig": { "anyKey": "anyValue" } }

OpenOTA never reads or acts on the value itself — what it means is entirely up to your app. Two things worth knowing: the endpoint sends Cache-Control: no-store, and this is a plain fetch() that does not inherit OTA.configure()'s requestTimeout — add your own AbortController timeout, or a slow/cold server can hang the request far longer than expected.

Real-time updates (optional)

By default a device only learns about a release the next time your app calls OTA.sync() — OpenOTA never polls on its own. To have the server nudge an already-open app instantly instead of waiting for the next launch or resume, open a live connection once:

OTA.connectLive(); // e.g. right after OTA.configure()
// ...
OTA.disconnectLive(); // e.g. on unmount

// or react to it yourself instead of the default silent OTA.sync():
OTA.connectLive(() => {
  console.log('a release just went out — re-checking now');
  OTA.sync();
});

Pure JS — React Native's built-in WebSocket, no native setup, no extra dependency. The server pushes a content-free "check now" nudge whenever a release, rollback, or rollout-percentage change happens on that device's channel; the real check endpoint (with its staged-rollout gate) stays the single source of truth for what a device is actually eligible for — nothing is pushed except the nudge itself. Reconnects automatically with backoff. Only reaches the app while it's open or backgrounded-but-alive — a fully closed app isn't woken up (that would need push notifications, which OpenOTA doesn't do yet).

Dashboard features (Cloud)

Environment variables

Full list including storage provider options: docs/CLOUD.md §5.

Reference app

OpenOTA_Example in the monorepo is a real, working OTA client — not a mock. Every screen talks to the live OpenOTA Cloud API through the real, published @openota/sdk and @openota/native-android packages: check for update, download, verify, install, and rollback, all real. It deliberately does not reimplement release/channel management — that stays on this dashboard, exactly the separation of concerns your own app should follow.

cd OpenOTA_Example
npm install
npm run android
npx @openota/cli release --version 1.0.1

import { OTA } from "@openota/sdk";
import config from "../../openota.config.json";

// One-time, module-level configure() — real values from openota.config.json, pointed at the live
// OpenOTA Cloud server. Everything this app shows/does from here on is driven by what that server
// returns; release/channel management itself happens on the OpenOTA Dashboard, not in this app.
OTA.configure({
  serverUrl: config.serverUrl,
  projectId: config.projectId,
  channel: "production",
  autoRestart: false, // let the UI show a clear "Update ready — restart" state first
});

// Live updates: the server nudges this connection the instant a new release/rollback/rollout
// change happens on this device's channel, instead of waiting for a manual check.
OTA.connectLive(() => setUpdateAvailable(true));

Troubleshooting

Real errors this project has actually surfaced, not a generic FAQ — each one either explains intentional behavior or names a bug that's already fixed in the current release.

Self-hosting & cloud setup

Two ways to run OpenOTA: self-hosted with Docker (your own infra, zero external accounts required), or Cloud mode across Render + Vercel (what powers api.openota.xyz and this dashboard today). Both run the exact same server code — this is a deployment choice, not a different product.

services:
  server:
    build:
      context: .
      dockerfile: apps/server/Dockerfile
    ports:
      - "${PORT:-3900}:${PORT:-3900}"
    env_file: [.env]
    volumes:
      - openota_storage:/data/storage
      - openota_pgdata:/repo/apps/server/data/pgdata

volumes:
  openota_storage:
  openota_pgdata:

Full environment variable reference, architecture, and API docs: docs/CLOUD.md in the repo.