Native execution and push

Use native execution for work owned by a registered compiled handler or a bundled declarative workflow. These APIs do not keep arbitrary background JavaScript running. Probe the selected executor and its configured kinds before showing a Start action.

import foreground from 'oro:foreground'
import continuous from 'oro:foreground/continuous'
import deferred from 'oro:background/deferred'

const finite = await foreground.getSupport()
const monitor = await continuous.getSupport()
const scheduled = await deferred.getSupport()
console.log(finite.available, finite.registeredKinds)
console.log(monitor.available, monitor.registeredKinds)
console.log(scheduled.available, scheduled.registeredKinds)

Choose an execution lifetime#

Android configuration separates these capabilities:

[foreground]
enabled = true
continuous_enabled = true
continuous_subtype = "User-started monitoring of account alerts"

[background]
deferred_enabled = true

Enable continuous execution only when the application actually offers a truthful user-started monitor and a Stop action. Finite and continuous starts carry opaque authority/account/target/operation references and userInitiated: true. They must name registered native kinds; enabling a flag does not register application code. Bundled workflows register their own runtime executors.

Retain controller IDs and generations. Stop/release operations are generation-bound; inspect status after admission rather than treating admission as success. An interrupted operation can be unknown and needs application reconciliation. Deferred work has bounded attempts, explicit resume/cancel/release, and platform periodic minimums. Force-stop and process loss are not promises of continued execution.

On Linux, application-process execution does not imply boot startup or survival after process exit. Optional native session hosting and cold activation are separate deployment choices. Other new platform backends report unavailable or ENOSYS; iOS unbounded background execution is restricted. See platform support.

Configure UnifiedPush#

[push]
enabled = true
provider = "unifiedpush"

Use oro:push to discover transport support, choose an installed distributor, and register a compiled native handler or workflow. Android supports Oro Push Dev and existing distributors such as ntfy. Linux uses UnifiedPush D-Bus services; multiple unselected distributors require an explicit choice.

Endpoint registration is asynchronous. Re-read the registration after resume or pushchange, authenticate enrollment with your application server, and acknowledge its exact generation. Registration objects contain sensitive enrollment material; do not log them. Registration, durable native receipt, application handling, notification submission, display, and remote completion are distinct outcomes.

Push journals and retries are bounded. Inspect pending/exhausted state and use the documented recovery operations for the exact retained generation. Do not silently delete unreadable journals, replace missing keys, or replay an uncertain application mutation. Workflow push messages are read hints, not executable code or arbitrary notification content.

Run development tools#

For a host-only server check:

oroc push server --host=127.0.0.1 --port=8787

This anonymous ntfy-backed server is for public test data on private development networks. First use downloads a pinned, checksum-verified ntfy release; --offline requires the verified cache or --ntfy-bin. Automatic server installation supports Linux x64/arm64 and Windows x64. On macOS, supply a server-enabled ntfy binary; the upstream macOS release is client-only.

Android distributors and application servers need a reachable HTTPS origin, a trusted certificate, and encrypted Web Push payloads. Loopback HTTP is for local checks, not Android registration. Configure HTTPS directly or use a local reverse proxy; see push server for certificate options.

After provisioning the Android toolchain, build/install the development distributor against your own HTTPS server:

oroc push distributor --server=https://push.dev.example:8787 --ca-cert=./dev-ca.pem --install --device=emulator-5554

Replace the hostname, CA path, and device serial. The separate APK requires the user to enable its visible foreground connection. It is not production server authentication. Native Android builds use JDK 17+; editor qualification's Java 21 requirement is separate. Gradle 9, Android platform 34+, build tools, and initially downloadable Android/Kotlin dependencies are required.

Linux development uses a native D-Bus distributor instead of an APK:

oroc push distributor --platform=linux --server=http://127.0.0.1:8787 --allow-loopback-http

This explicit loopback-only HTTP exception is for development. The Linux command requires a session D-Bus, an unlocked Secret Service, and an ntfy-compatible server; it does not require Node, Gradle, or the Android SDK. It runs until interrupted and does not install a login service. See push distributor for bounded polling, encrypted retention, trust, and recovery behavior.

Continue#

Use the Android integration reference for native handler registration, cold startup, enrollment, and journal recovery. The Linux reference explains optional persistent hosting and the corresponding platform limits.