OpenFault

Push & iOS app

The iOS app is in development (TestFlight first). The server side below is built; app details may still change.

Why a relay

Apple only accepts pushes signed with the APNs key of whoever ships the app. Your server should not hold our key, and we should not hold your data. So your server sends pushes through a small relay that holds the key. The relay only ever receives device tokens, the issue title, the project name and the deep link.

Push is off until you opt in by setting a relay URL and token, in the setup wizard’s second step, Settings → Organization → Push relay, over MCP with configure_push_relay, or with the two environment variables below (which override the stored values).

Hosted relay (App Store app)

Opt in with relay URL https://push.openfault.dev and the token you were given. As environment variables:

OPENFAULT_PUSH_RELAY_URL=https://push.openfault.dev
OPENFAULT_PUSH_RELAY_TOKEN=<the token you were given>
OPENFAULT_BASE_URL=https://errors.example.com

Self-run relay

The relay is the same image in a second mode:

docker run -d -p 8081:8080 \
  -e APNS_KEY_P8_FILE=/keys/AuthKey_ABC123.p8 -v $PWD/keys:/keys:ro \
  -e APNS_KEY_ID=ABC123 -e APNS_TEAM_ID=TEAM123456 -e APNS_BUNDLE_ID=com.example.openfault \
  -e RELAY_TOKEN=$(openssl rand -hex 32) \
  ghcr.io/openfault/openfault:latest relay
VariableMeaning
APNS_KEY_P8 / APNS_KEY_P8_FILEThe .p8 key as PEM text (literal \n allowed), or a path to it.
APNS_KEY_ID, APNS_TEAM_IDFrom your Apple developer account.
APNS_BUNDLE_IDThe iOS app’s bundle id (the APNs topic).
RELAY_TOKENServers must send Authorization: Bearer <RELAY_TOKEN>.
APNS_SANDBOX1 sends to the APNs development host, for debug builds from Xcode.
PORTListen port, default 8080.

Then point your server at it with OPENFAULT_PUSH_RELAY_URL and OPENFAULT_PUSH_RELAY_TOKEN.

Endpoints: POST /v1/push with {tokens, title, body, url, collapse_id} returns a {token, status, reason} per token, and GET /healthz. Tokens APNs reports as gone are deleted on your server.

Pushes only reach a build signed with the same team and bundle id as the relay’s key. To stay fully self-sovereign, build the open-source openfault-ios app with your own Apple account and bundle id, run the relay with your key, and point your server at it.

Pairing a phone

Pairing gives the phone its own write token, tied to that device. No password is typed on the phone.

  1. In the web UI, open Settings → Devices → Pair a phone (or call POST /api/v1/pair/start). That shows an 8-character code (no 0, O, 1 or I) and a QR code for openfault://pair?host=…&code=….
  2. Scan the QR with the app, or type the host and code.
  3. The phone claims the code and gets its token, the user and the project list.

Codes expire after 10 minutes and work once. You can have 5 open at a time. Failed claims are rate limited per IP (10 per 15 minutes).

Settings → Devices lists your paired phones. Removing one there, in the app or via DELETE /api/v1/me/devices/{id} revokes its token. Re-pairing the same phone revokes the old token.

What the app does

Dashboard, issue list with filters, issue detail, resolve / mute / approve / assign, releases and notification preferences. Push for new issues, regressions and spikes, deep-linked to the issue.

Widgets