Mobile SDK

Orch8 compiles to native iOS and Android libraries via UniFFI. The same Rust engine that runs on servers executes workflows locally on mobile devices — offline-first, battery-aware, with server-side visibility and control.

The mobile runtime is an Orch8-specific execution target. It supports a defined subset of sequence behavior on iOS and Android; use the compatibility matrix below when deciding what can run locally.

1git clone https://github.com/orch8-io/engine.git
2cd engine/mobile-examples
3open ios/Orch8Example/Orch8Example.xcodeproj
4# Android: open mobile-examples/android in Android Studio

Architecture

Mobile workflows follow a simple principle: the device is autonomous, the server is the mailbox.

1Mobile Device                     Server                        Dashboard
2---------------------------------------------------------------------
3
4[run sequences locally]
5[accumulate status changes]
6[hit wait_for_input]
7
8  --POST /mobile/sync---------->  [store status updates]
9    { status_updates,              [store approval requests]
10      approval_requests,           [return pending commands]
11      command_acks }               [return sync_interval_hint]
12  <----response-----------------
13    { commands, sync_interval }
14
15                    ... mobile sleeps ...
16
17                                                          [admin sees workflows]
18                                                          [admin approves/cancels]
19                                  [queue command]
20                                  [send silent push]
21
22  <--silent push notification---
23  [wake up]
24  --POST /mobile/sync---------->  [drain commands]
25  <----response-----------------
26    { commands: [complete_step] }
27  [execute command locally]
28  [complete_step / cancel / etc]

Design principles

• —Offline-capable execution — Supported local steps can advance without a connection; sync, remote commands, and server-backed operations wait for connectivity.
• —Server is the mailbox — Stores status, queues commands, dispatches push notifications. Never executes mobile workflows.
• —Batched sync — A sync request can carry status updates, approval requests, command acknowledgements, and pending server commands.
• —Push-driven wake — Mobile sleeps when idle, wakes on silent push notification. No fixed-interval polling.
• —Battery-first — Adaptive sync intervals, state coalescing, power-state multipliers. No unnecessary radio wake-ups.

Sync Protocol

All mobile-server communication flows through a single bidirectional endpoint. The device sends status updates and approval requests; the server returns pending commands and a sync interval hint.

Request: POST /mobile/sync

1{
2  "device_id": "device-abc-123",
3  "status_updates": [
4    {
5      "instance_id": "uuid",
6      "sequence_name": "onboarding-flow",
7      "state": "Waiting",
8      "current_step": "request_approval",
9      "handler": "request_approval",
10      "timestamp": "2026-05-19T10:30:00Z",
11      "context_summary": {}
12    }
13  ],
14  "approval_requests": [
15    {
16      "instance_id": "uuid",
17      "block_id": "step-3",
18      "prompt": "Action requires approval. Please review and decide.",
19      "choices": [
20        { "label": "Approve", "value": "approved" },
21        { "label": "Reject", "value": "rejected" }
22      ],
23      "store_as": "approval_result",
24      "timeout_seconds": 86400,
25      "metadata": {}
26    }
27  ],
28  "command_acks": ["cmd-001", "cmd-002"]
29}

Response

1{
2  "commands": [
3    {
4      "id": "cmd-003",
5      "type": "complete_step",
6      "instance_id": "uuid",
7      "step_name": "request_approval",
8      "output": "{\"value\":\"approved\"}"
9    },
10    {
11      "id": "cmd-004",
12      "type": "cancel_instance",
13      "instance_id": "uuid-2"
14    }
15  ],
16  "sync_interval_secs": 30
17}

Command types

Idempotency

• —Commands are keyed by id. Mobile ACKs after execution. Server re-delivers unACKed commands on next sync.
• —Approval requests are keyed by (device_id, instance_id, block_id). Duplicate POSTs are ignored.
• —Status updates are last-write-wins per (device_id, instance_id). Latest state overwrites.

Adaptive Sync Intervals

Mobile does not poll on a fixed timer. The sync cycle piggybacks on the engine tick loop via a tick counter. The server dynamically adjusts the interval based on pending work.

Push Notifications

Push notifications are a content-less "sync now" signal. They carry no commands or data. The sync endpoint is the single source of truth.

Why push as signal only

• —Push delivery is unreliable (can be dropped, delayed, reordered)
• —Push payload size is limited (4KB APNs, varies FCM)
• —Commands need ACK/retry semantics that push doesn't provide
• —Single source of truth prevents split-brain between push payload and server state

Platform specifics

The operating system decides whether and for how long background work runs; silent push is a wake-up hint, not a delivery or runtime guarantee.

Host app responsibility

The engine does NOT handle push registration or receiving. The host app (Swift/Kotlin) must:

1. Register for remote notifications with the OS
2. Pass the push token to the engine via register_push_token(token)
3. On receiving a silent push, call engine.on_push_received()
4. The engine wakes its scheduler and starts a sync cycle; actual timing depends on OS scheduling, connectivity, and configured intervals

Approval Flow

When a mobile workflow hits a wait_for_input step, it sends an approval request to the server. An admin resolves it from the dashboard, and the resolution flows back to the device via push + sync.

11. Mobile workflow reaches wait_for_input step
22. Mobile sends approval_request in next sync
33. Server stores approval (state: pending)
44. Dashboard shows approval to admin
5
65. Admin clicks "Approve"
76. Server resolves approval, creates complete_step command
87. Server sends silent push to device
9
108. Device wakes, syncs, receives command
119. Device calls engine.complete_step()
1210. Workflow continues from where it left off

Offline Behavior

When the device is offline, workflows continue executing locally. Status changes and approval requests accumulate in a local SQLite outbox. When connectivity returns, the next sync drains the full outbox in a single request.

• —Workflows advance independently of server availability
• —State changes coalesce — multiple transitions for the same instance collapse to the latest state
• —Sync attempts fail silently (logged, counter reset to retry later)
• —Commands queued on the server are delivered on the first successful sync

Server API Endpoints

All endpoints require x-api-key (tenant API key) and x-device-id headers. All queries are scoped by tenant_id for full tenant isolation.

0.7 Device Capability Mesh

A registered device can advertise a short-lived mobile runtime throughPOST /mobile/devices/{device_id}/runtime. The server adds the hardware capabilitydevice:{id} and makes live handler, hardware, region, trust, connectivity, battery, cost, latency, offline, and drain facts available to placement policy.

1{
2  "runtime_kind": "mobile",
3  "handlers": ["camera.capture", "model.local_inference"],
4  "hardware": ["camera", "neural_engine"],
5  "regions": ["br-south"],
6  "trust": "registered",
7  "connectivity": "wifi",
8  "battery_percent": 78,
9  "estimated_cost_microunits": 0,
10  "estimated_latency_ms": 40,
11  "offline": true,
12  "draining": false
13}

Placement preview returns the selected runtime, rejected candidates, aplacement_decision_id, andpreview_sha256. Handoff creation must echo both; the engine rechecks live facts at creation and export.

Outbound federation usesPOST /continuity/federation/sign to create a destination-bound envelope with a lifetime of at most five minutes. The caller transports the envelope and unchanged payload to the peer's/continuity/federation/verify endpoint; signing does not perform an implicit network request.

Configuration

Mobile sync is disabled by default. Enable it and configure push notifications via environment variables or TOML config.

1# Enable mobile sync
2ORCH8_MOBILE_SYNC_ENABLED=true
3
4# Push provider: "apns", "fcm", or "" (disabled)
5ORCH8_PUSH_PROVIDER=apns
6
7# APNs configuration
8ORCH8_APNS_KEY_PATH=/secrets/apns-auth-key.p8
9ORCH8_APNS_KEY_ID=ABC123DEFG
10ORCH8_APNS_TEAM_ID=TEAM123456
11ORCH8_APNS_TOPIC=io.orch8.example
12
13# Or FCM configuration
14# ORCH8_PUSH_PROVIDER=fcm
15# ORCH8_FCM_CREDENTIALS_PATH=/secrets/firebase-sa.json
16# ORCH8_FCM_PROJECT_ID=my-project-id
17
18# Limits
19ORCH8_MOBILE_SYNC_MAX_DEVICES=1000
20ORCH8_MOBILE_SYNC_COMMAND_TTL_SECS=604800
21ORCH8_MOBILE_SYNC_APPROVAL_TTL_SECS=86400

TOML config

1[mobile_sync]
2enabled = true
3max_devices = 1000
4command_ttl_secs = 604800
5approval_ttl_secs = 86400
6
7[mobile_sync.push]
8provider = "apns"
9
10[mobile_sync.push.apns]
11key_path = "/secrets/apns-auth-key.p8"
12key_id = "ABC123DEFG"
13team_id = "TEAM123456"
14topic = "io.orch8.example"
15sandbox = false

Deployment

Docker

1docker run --rm -p 8080:8080 \
2  -e ORCH8_MOBILE_SYNC_ENABLED=true \
3  -e ORCH8_PUSH_PROVIDER=apns \
4  -e ORCH8_APNS_KEY_ID=ABC123DEFG \
5  -e ORCH8_APNS_TEAM_ID=TEAM123456 \
6  -e ORCH8_APNS_TOPIC=io.orch8.example \
7  -v /path/to/apns-key.p8:/secrets/apns-auth-key.p8:ro \
8  -e ORCH8_APNS_KEY_PATH=/secrets/apns-auth-key.p8 \
9  ghcr.io/orch8-io/engine:0.7.1

No push provider

When ORCH8_PUSH_PROVIDER is empty, the engine uses a no-op provider. Push calls are silently ignored. Mobile relies entirely on heartbeat polling (10-15 min). This is valid for development, staging, or when push infrastructure is unavailable.

Multi-replica

Mobile sync is stateless — any engine replica can serve any device. The database is the coordination point. No sticky sessions needed. Push dispatch is fire-and-forget with heartbeat fallback.

Security

• —Authentication — Same tenant API key as other endpoints. Device identity via x-device-id header (UUID generated on first launch).
• —Tenant isolation — All queries scoped by tenant_id. A device can only see/affect instances belonging to its tenant.
• —Command validation — Server validates commands before queuing — verifies approval exists and is pending, verifies instance belongs to device.
• —Push token security — Push tokens stored server-side only, never exposed via API. Silent push contains no sensitive data.