Preview

You're viewing the Next docs — a rolling preview of in-development changes. The current release docs may differ.

App Updates

This reference defines the contract between Nexigon and the app integrations on devices: the dev.nexigon.apps.config and dev.nexigon.apps.status properties and the nexigon.apps.check command. An app integration installs, updates, and removes the apps on a device independently of its system, such as the Rugix Apps integration of Nexigon Agent. To deploy an app, follow Application Workloads.

The contract follows the update model of system updates: Nexigon Hub stores the desired state, and the device converges toward it and reports its progress. It reuses the maintenance windows, retry policies, and spreads of OTA updates.

The contract is unstable and may still change in incompatible ways.

Interface

Name	Kind	Usage	Purpose
`dev.nexigon.apps.config`	Protected property	Written by operators	Desired state of the device apps
`dev.nexigon.apps.status`	Property	Written by the device	Actual state of the device apps
`nexigon.apps.check`	Device command	Registered by the device, run by operators	Requests an immediate check

Configuration Property

dev.nexigon.apps.config lists the apps that the integration manages under apps, by app name. The integration leaves installed apps that the property does not list untouched.

dev.nexigon.apps.config

{
  "window": { "ranges": [{ "start": "02:00", "end": "05:00" }] },
  "apps": {
    "controller": { "path": "acme/controller/stable" },
    "historian": {
      "path": "acme/historian/pkg_v_3sLgP9eKd7XwHn2QaRt5Zm",
      "hold": true
    },
    "legacy-bridge": { "state": "removed" }
  }
}

The policies hold, window, retry, spread, and gc apply to every app that does not set its own. Except for gc, they have the same format and meaning as in dev.nexigon.ota.config. They govern version changes. A change of an app’s state applies at the next check, regardless of the policies.

Field	Description
`apps`	Managed apps by name. Each app has the fields below.
`hold`	Holds all apps at their current versions while `true`. The device neither installs nor activates new versions.
`window`	Maintenance window restricting when the device switches a running app to a new version.
`retry`	Retry policy for failed attempts.
`spread`	Spread of updates across devices. The position of a device depends on the target version of each app.
`gc`	Removal of old versions after an update. See Old Versions.

App Field	Description
`path`	Version path in the format `<repository>/<package>/<version>`. Without a path, the integration only applies `state` to an installed app.
`asset`	Filename of the bundle to install. `{arch}` stands for the architecture of the device. See Bundle Selection for the default.
`state`	Desired state: `running` (default), `stopped`, or `removed`.
`hold`, `window`, `retry`, `spread`, and `gc`	Policies of the app, which replace those of the configuration. For example, `"hold": false` exempts the app from a hold of all apps.
`rollout`	Rollout number. Integrations ignore its value. Changing it starts a new round of attempts of the app on devices whose attempts failed.

The desired states have these effects:

running: The app is installed and its workload runs.
stopped: The app is installed but deactivated. Its workload does not run, also not after a reboot. Version changes of a stopped app install the new version without starting it.
removed: The app is uninstalled, including its persistent data.

Removing an app from apps ends its management but leaves it installed. To uninstall an app, set its state to removed.

Device profiles apply the property as a JSON merge patch, so a profile can add, change, or remove a single app without repeating the others. For example, a profile setting { "apps": { "historian": null } } ends the management of historian on the devices that apply the profile.

Bundle Selection

A package version can contain bundles of an app for several architectures. The integration installs the bundle for the architecture of the device, which it reports as arch in the status. Nexigon Agent uses Rust’s architecture names, such as x86_64, aarch64, or arm.

Without asset, the integration installs <app>-<arch>.rugixb, or <app>.rugixb if the version has no bundle for the architecture. Use the second name for bundles that run on every architecture. For example, a version of the controller app for two architectures contains:

controller-x86_64.rugixb
controller-aarch64.rugixb

If the version has no matching bundle, the app is blocked with the code no-asset.

Check Cycle

The integration checks the apps periodically, after the device connects, when an attempt is due, and when someone runs the nexigon.apps.check command. For each managed app, a check performs these steps:

Apply the desired state. A removed app is uninstalled, a stopped app is stopped, and a running app is started. An app that starts while its target version is installed starts with the target version.
Resolve the path to the target version.
Unless a hold, a spread, or a retry policy defers the update, install the bundle of the target version without interrupting the app.
Switch the app to the new version, unless the maintenance window is closed while the app runs. A closed window leaves the installed version waiting for the window.
Remove old versions of the app, as the gc policy defines.
Publish the status.

The device records the package version of every installation, so it knows which version an app runs without relying on the previous status. If the target version is still installed from an earlier update, the device switches back to it without downloading it again.

Old Versions

After switching an app to a new version, the integration removes old versions of the app to free storage. It keeps the running version and the most recent previously running versions. An installed version that has not run yet stays until it or a newer version runs.

dev.nexigon.apps.config

{
  "gc": { "keep": 1 },
  "apps": {
    "historian": { "path": "acme/historian/stable", "gc": { "keep": 3 } }
  }
}

Field	Description
`keep`	Number of previously running versions to keep. Defaults to the integration’s default. Nexigon Agent keeps 1 unless its configuration sets `gc.keep`.

Keeping more versions makes switching back faster and works without a connection to the repository, at the cost of storage.

Status Property

The integration publishes dev.nexigon.apps.status to report the status of every managed and every installed app.

dev.nexigon.apps.status

{
  "capabilities": ["hold", "asset", "window", "retry", "spread", "gc"],
  "configVersion": 12,
  "arch": "aarch64",
  "runtime": { "name": "rugix", "version": "1.4.0" },
  "apps": {
    "controller": {
      "managed": true,
      "config": { "path": "acme/controller/stable", "state": "running" },
      "state": "blocked",
      "blocked": { "code": "window" },
      "generation": 3,
      "currentVersionId": "pkg_v_7Hq2mWbXc9RtLpZ3sNfE1k",
      "targetVersionId": "pkg_v_3sLgP9eKd7XwHn2QaRt5Zm",
      "asset": "controller-aarch64.rugixb",
      "failureCount": 0,
      "workload": { "state": "running" }
    },
    "debug-shell": {
      "managed": false,
      "generation": 1,
      "workload": { "state": "stopped" }
    }
  }
}

Field	Description
`capabilities`	Optional features that the integration supports: `hold`, `asset`, `window`, `retry`, `spread`, and `gc`.
`configVersion`	Version of `dev.nexigon.apps.config` that the integration last read.
`lastError`	Why the integration cannot apply the configuration, for example because the property is invalid.
`arch`	Architecture of the device, which selects the bundles it installs.
`runtime`	Runtime that installs and runs the apps, with its `name` and `version`.
`apps`	Status of every managed and every installed app, by name.

App Field	Description
`managed`	Whether `dev.nexigon.apps.config` lists the app.
`config`	Effective configuration of the app, including the policies that apply to it.
`state`	State of the app’s update process.
`blocked`	Present when `state` is `blocked`. Contains a code and an optional human-readable `message`.
`generation`	Installation of the app that runs, or that runs when the app starts.
`currentVersionId`	Package version of `generation`. Absent when the integration did not install it.
`targetVersionId`	Package version that the configured path resolves to.
`asset`	Filename of the bundle that the integration installs from the target version.
`failureCount`	Consecutive failed attempts for the target version. Resets when the target version or the effective configuration of the app changes.
`lastError`	Error message of the last failure.
`nextAttemptAt`	Earliest time of the next attempt, while the app waits for a spread, a maintenance window, a retry delay, or a retry cooldown.
`workload`	Live status of the app’s workload: `running`, `unhealthy`, `stopped`, `failed`, or `unknown`, with a `message` for `unhealthy` and `failed`.

States

State	Meaning
`idle`	No path is configured.
`installing`	A new version is being downloaded and installed without interrupting the app.
`activating`	The app is switching to the installed version.
`removing`	The app is being uninstalled.
`completed`	The app has the target version and its desired state, or it has been uninstalled as desired.
`failed`	The last attempt failed. `lastError` explains why.
`blocked`	An update is available but cannot proceed yet. See `blocked` for the reason.

If activating a new version fails, Rugix Apps restores the previous version, and the app reports failed while it keeps running the previous version.

Blocked Codes

Code	Meaning
`hold`	The configuration holds the app at its current version.
`spread`	The device waits for its turn in a spread or is outside the released percentage.
`window`	The device waits for its maintenance window. The new version may already be installed.
`no-asset`	The target version has no bundle for the device’s architecture or no available asset with the filename in `asset`.

Requesting a Retry

The integration writes the status with the version it read last (compare-and-swap). Other writers may only remove the failureCount and nextAttemptAt of an app, which requests a new attempt at the next check. Retry Update in the web interface does this.

Sidex Schema

The properties Sidex schema defines the property formats:

schema`properties`

Types related to device properties.

record

`AppUpdateConfig`

Unstable (feature app_updates)

App update configuration (dev.nexigon.apps.config).

Desired state of the apps on a device. The integration manages the apps listed in apps and leaves other installed apps untouched. Removing an app from apps ends its management without uninstalling it. To uninstall an app, set its state to removed.

The policies hold, window, retry, spread, and gc apply to every app that does not set its own. They govern version changes. Changes of an app's state apply at the next check.

Fields (JSON object)

appsoptional
Managed apps by name.
object<string, ManagedAppConfig>
Keys
string
Values
ManagedAppConfig
Fields (JSON object)
pathoptional
Version path in the format <repository>/<package>/<version>.

<version> is a tag or a version ID. A tag tracks the version the tag points to. A version ID pins a single version. Without a path, the integration does not install or update the app and only applies state to an installed app.

string
assetoptional
Filename of the bundle that the device installs from a version.

{arch} stands for the architecture of the device. Defaults to <app>-{arch}.rugixb, or to <app>.rugixb if the version has no bundle for the architecture.

string
stateoptional
Desired state of the app. Defaults to running.

AppDesiredState
Casesexternally
Running→ "running"
The app is installed and its workload runs.

Value: "running"
Stopped→ "stopped"
The app is installed but deactivated, so that its workload does not run, also not after a reboot.

Value: "stopped"
Removed→ "removed"
The app is uninstalled, including its persistent data.

Value: "removed"
holdoptional
Hold the app at its current version.

boolean
windowoptional
Maintenance window restricting when updates of the app are activated.

OtaUpdateWindow
Fields (JSON object)
rangesrequired
Time ranges in which updates can be activated.

An empty list never allows activation.

array<OtaUpdateWindowRange>
Items
OtaUpdateWindowRange
Fields (JSON object)
daysoptional
Days on which the range starts.

Defaults to every day.

array<Weekday>
Items
Weekday
Casesexternally
Monday→ "monday"
Value: "monday"
Tuesday→ "tuesday"
Value: "tuesday"
Wednesday→ "wednesday"
Value: "wednesday"
Thursday→ "thursday"
Value: "thursday"
Friday→ "friday"
Value: "friday"
Saturday→ "saturday"
Value: "saturday"
Sunday→ "sunday"
Value: "sunday"
startrequired
Start of the range (inclusive).

TimeOfDay
Wraps
string
endrequired
End of the range (exclusive).

An end at or before the start lies on the following day. A range whose end equals its start therefore spans 24 hours.

TimeOfDay
Wraps
string
retryoptional
Retry policy for failed update attempts of the app.

OtaUpdateRetryPolicy
Fields (JSON object)
maxAttempts(from max_attempts)optional
Maximum number of failed attempts for a version.

Unlimited when absent.

integer
initialDelaySecs(from initial_delay_secs)optional
Delay before the first retry in seconds.

integer
maxDelaySecs(from max_delay_secs)optional
Maximum delay between attempts in seconds.

integer
cooldownSecs(from cooldown_secs)optional
Time in seconds after reaching max_attempts before the failure count resets and a new round of attempts begins.

Without a cooldown, the device stops attempting the version until the version of the configuration changes or the failure count is cleared.

integer
spreadoptional
Spreading of updates of the app across devices.

OtaUpdateSpread
Fields (JSON object)
durationSecs(from duration_secs)optional
Time over which updates are spread, in seconds.

integer
startAt(from start_at)optional
Start of the spread over time.

Defaults to the time at which the tag in the configured path was assigned to its current version. Without an explicit start, updates to versions configured by version ID are not spread over time.

Timestamp
percentageoptional
Share of devices that may update, in percent.

Raising the percentage only adds devices. Without duration_secs, it releases the update to the given share right away. With duration_secs, it caps the share of the spread over time.

number
gcoptional
Removal of old versions of the app after an update.

AppGcPolicy
Fields (JSON object)
keepoptional
Number of previously running versions to keep.

Defaults to the integration's default, usually 1.

integer
rolloutoptional
Rollout number.

Integrations ignore its value. Changing it changes the app's configuration, which starts a new round of attempts on devices whose attempts failed.

integer
holdoptional
Hold all apps at their current versions.

While set, the device neither installs nor activates new versions. An update in progress completes. Defaults to false.

boolean
windowoptional
Maintenance window restricting when updates are activated.

Outside the window, the device may download and install a new version of a running app without activating it. Updates can be activated at any time when absent.
OtaUpdateWindow
Fields (JSON object)
rangesrequired
Time ranges in which updates can be activated.

An empty list never allows activation.

array<OtaUpdateWindowRange>
Items
OtaUpdateWindowRange
Fields (JSON object)
daysoptional
Days on which the range starts.

Defaults to every day.

array<Weekday>
Items
Weekday
Casesexternally
Monday→ "monday"
Value: "monday"
Tuesday→ "tuesday"
Value: "tuesday"
Wednesday→ "wednesday"
Value: "wednesday"
Thursday→ "thursday"
Value: "thursday"
Friday→ "friday"
Value: "friday"
Saturday→ "saturday"
Value: "saturday"
Sunday→ "sunday"
Value: "sunday"
startrequired
Start of the range (inclusive).

TimeOfDay
Wraps
string
endrequired
End of the range (exclusive).

An end at or before the start lies on the following day. A range whose end equals its start therefore spans 24 hours.

TimeOfDay
Wraps
string
retryoptional
Retry policy for failed update attempts.
OtaUpdateRetryPolicy
Fields (JSON object)
maxAttempts(from max_attempts)optional
Maximum number of failed attempts for a version.

Unlimited when absent.

integer
initialDelaySecs(from initial_delay_secs)optional
Delay before the first retry in seconds.

integer
maxDelaySecs(from max_delay_secs)optional
Maximum delay between attempts in seconds.

integer
cooldownSecs(from cooldown_secs)optional
Time in seconds after reaching max_attempts before the failure count resets and a new round of attempts begins.

Without a cooldown, the device stops attempting the version until the version of the configuration changes or the failure count is cleared.

integer
spreadoptional
Spreading of updates across devices.

Devices update without waiting when absent.
OtaUpdateSpread
Fields (JSON object)
durationSecs(from duration_secs)optional
Time over which updates are spread, in seconds.

integer
startAt(from start_at)optional
Start of the spread over time.

Defaults to the time at which the tag in the configured path was assigned to its current version. Without an explicit start, updates to versions configured by version ID are not spread over time.

Timestamp
percentageoptional
Share of devices that may update, in percent.

Raising the percentage only adds devices. Without duration_secs, it releases the update to the given share right away. With duration_secs, it caps the share of the spread over time.

number
gcoptional
Removal of old versions after an update.
AppGcPolicy
Fields (JSON object)
keepoptional
Number of previously running versions to keep.

Defaults to the integration's default, usually 1.

integer

record

`ManagedAppConfig`

Unstable (feature app_updates)

Desired state of a managed app.

A policy set here replaces the policy of the configuration for this app.

Fields (JSON object)

pathoptional
Version path in the format <repository>/<package>/<version>.

<version> is a tag or a version ID. A tag tracks the version the tag points to. A version ID pins a single version. Without a path, the integration does not install or update the app and only applies state to an installed app.

string
assetoptional
Filename of the bundle that the device installs from a version.

{arch} stands for the architecture of the device. Defaults to <app>-{arch}.rugixb, or to <app>.rugixb if the version has no bundle for the architecture.

string
stateoptional
Desired state of the app. Defaults to running.
AppDesiredState
Casesexternally
Running→ "running"
The app is installed and its workload runs.

Value: "running"
Stopped→ "stopped"
The app is installed but deactivated, so that its workload does not run, also not after a reboot.

Value: "stopped"
Removed→ "removed"
The app is uninstalled, including its persistent data.

Value: "removed"
holdoptional
Hold the app at its current version.

boolean
windowoptional
Maintenance window restricting when updates of the app are activated.
OtaUpdateWindow
Fields (JSON object)
rangesrequired
Time ranges in which updates can be activated.

An empty list never allows activation.

array<OtaUpdateWindowRange>
Items
OtaUpdateWindowRange
Fields (JSON object)
daysoptional
Days on which the range starts.

Defaults to every day.

array<Weekday>
Items
Weekday
Casesexternally
Monday→ "monday"
Value: "monday"
Tuesday→ "tuesday"
Value: "tuesday"
Wednesday→ "wednesday"
Value: "wednesday"
Thursday→ "thursday"
Value: "thursday"
Friday→ "friday"
Value: "friday"
Saturday→ "saturday"
Value: "saturday"
Sunday→ "sunday"
Value: "sunday"
startrequired
Start of the range (inclusive).

TimeOfDay
Wraps
string
endrequired
End of the range (exclusive).

An end at or before the start lies on the following day. A range whose end equals its start therefore spans 24 hours.

TimeOfDay
Wraps
string
retryoptional
Retry policy for failed update attempts of the app.
OtaUpdateRetryPolicy
Fields (JSON object)
maxAttempts(from max_attempts)optional
Maximum number of failed attempts for a version.

Unlimited when absent.

integer
initialDelaySecs(from initial_delay_secs)optional
Delay before the first retry in seconds.

integer
maxDelaySecs(from max_delay_secs)optional
Maximum delay between attempts in seconds.

integer
cooldownSecs(from cooldown_secs)optional
Time in seconds after reaching max_attempts before the failure count resets and a new round of attempts begins.

Without a cooldown, the device stops attempting the version until the version of the configuration changes or the failure count is cleared.

integer
spreadoptional
Spreading of updates of the app across devices.
OtaUpdateSpread
Fields (JSON object)
durationSecs(from duration_secs)optional
Time over which updates are spread, in seconds.

integer
startAt(from start_at)optional
Start of the spread over time.

Defaults to the time at which the tag in the configured path was assigned to its current version. Without an explicit start, updates to versions configured by version ID are not spread over time.

Timestamp
percentageoptional
Share of devices that may update, in percent.

Raising the percentage only adds devices. Without duration_secs, it releases the update to the given share right away. With duration_secs, it caps the share of the spread over time.

number
gcoptional
Removal of old versions of the app after an update.
AppGcPolicy
Fields (JSON object)
keepoptional
Number of previously running versions to keep.

Defaults to the integration's default, usually 1.

integer
rolloutoptional
Rollout number.

Integrations ignore its value. Changing it changes the app's configuration, which starts a new round of attempts on devices whose attempts failed.

integer

variant

`AppDesiredState`

Unstable (feature app_updates)

Desired state of a managed app.

Casesexternally

Running→ "running"
The app is installed and its workload runs.

Value: "running"
Stopped→ "stopped"
The app is installed but deactivated, so that its workload does not run, also not after a reboot.

Value: "stopped"
Removed→ "removed"
The app is uninstalled, including its persistent data.

Value: "removed"

record

`AppGcPolicy`

Unstable (feature app_updates)

Removal of old versions of an app.

After switching an app to a new version, the integration removes old versions to free storage. It keeps the running version and the most recent previously running versions, to which the app can switch back without downloading them again.

Fields (JSON object)

keepoptional
Number of previously running versions to keep.

Defaults to the integration's default, usually 1.

integer

record

`AppUpdateStatus`

Unstable (feature app_updates)

App update status (dev.nexigon.apps.status).

Actual state of the apps on a device, published by its app integration.

The integration writes the status with the version it read last (compare-and-swap), so that it does not overwrite concurrent changes. Other writers may only clear the failure_count and next_attempt_at of an app, which requests a new attempt.

Fields (JSON object)

capabilitiesoptional
Optional features of the app update contract that the integration supports.
array<AppUpdateCapability>
Items
AppUpdateCapability
Casesexternally
Window→ "window"
The integration honors window.

Value: "window"
Retry→ "retry"
The integration honors retry and resets the failure count of an app when its configuration changes.

Value: "retry"
Spread→ "spread"
The integration honors spread.

Value: "spread"
Hold→ "hold"
The integration honors hold.

Value: "hold"
Asset→ "asset"
The integration honors asset.

Value: "asset"
Gc→ "gc"
The integration honors gc.

Value: "gc"
configVersion(from config_version)optional
Version of the dev.nexigon.apps.config property that the integration last read.

Absent when the property does not exist. The version changes with every write to the device's own value and whenever a profile revision that sets the property is applied to the device, even with an unchanged value.

integer (i64)
lastError(from last_error)optional
Why the integration cannot apply the configuration, if it cannot.

string
archoptional
Architecture of the device, which selects the bundles it installs.

string
runtimeoptional
Runtime that installs and runs apps on the device.
AppRuntime
Fields (JSON object)
namerequired
Name of the runtime, such as rugix.

string
versionoptional
Version of the runtime.

string
appsrequired
Managed and installed apps by name.
object<string, AppStatus>
Keys
string
Values
AppStatus
Fields (JSON object)
managedrequired
Whether dev.nexigon.apps.config lists the app.

boolean
configoptional
Effective configuration of the app, including the policies that apply to it.

ManagedAppConfig
Fields (JSON object)
pathoptional
Version path in the format <repository>/<package>/<version>.

<version> is a tag or a version ID. A tag tracks the version the tag points to. A version ID pins a single version. Without a path, the integration does not install or update the app and only applies state to an installed app.

string
assetoptional
Filename of the bundle that the device installs from a version.

{arch} stands for the architecture of the device. Defaults to <app>-{arch}.rugixb, or to <app>.rugixb if the version has no bundle for the architecture.

string
stateoptional
Desired state of the app. Defaults to running.

AppDesiredState
Casesexternally
Running→ "running"
The app is installed and its workload runs.

Value: "running"
Stopped→ "stopped"
The app is installed but deactivated, so that its workload does not run, also not after a reboot.

Value: "stopped"
Removed→ "removed"
The app is uninstalled, including its persistent data.

Value: "removed"
holdoptional
Hold the app at its current version.

boolean
windowoptional
Maintenance window restricting when updates of the app are activated.

OtaUpdateWindow
Fields (JSON object)
rangesrequired
Time ranges in which updates can be activated.

An empty list never allows activation.

array<OtaUpdateWindowRange>
Items
OtaUpdateWindowRange
Fields (JSON object)
daysoptional
Days on which the range starts.

Defaults to every day.

array<Weekday>
Items
Weekday
Casesexternally
Monday→ "monday"
Value: "monday"
Tuesday→ "tuesday"
Value: "tuesday"
Wednesday→ "wednesday"
Value: "wednesday"
Thursday→ "thursday"
Value: "thursday"
Friday→ "friday"
Value: "friday"
Saturday→ "saturday"
Value: "saturday"
Sunday→ "sunday"
Value: "sunday"
startrequired
Start of the range (inclusive).

TimeOfDay
Wraps
string
endrequired
End of the range (exclusive).

An end at or before the start lies on the following day. A range whose end equals its start therefore spans 24 hours.

TimeOfDay
Wraps
string
retryoptional
Retry policy for failed update attempts of the app.

OtaUpdateRetryPolicy
Fields (JSON object)
maxAttempts(from max_attempts)optional
Maximum number of failed attempts for a version.

Unlimited when absent.

integer
initialDelaySecs(from initial_delay_secs)optional
Delay before the first retry in seconds.

integer
maxDelaySecs(from max_delay_secs)optional
Maximum delay between attempts in seconds.

integer
cooldownSecs(from cooldown_secs)optional
Time in seconds after reaching max_attempts before the failure count resets and a new round of attempts begins.

Without a cooldown, the device stops attempting the version until the version of the configuration changes or the failure count is cleared.

integer
spreadoptional
Spreading of updates of the app across devices.

OtaUpdateSpread
Fields (JSON object)
durationSecs(from duration_secs)optional
Time over which updates are spread, in seconds.

integer
startAt(from start_at)optional
Start of the spread over time.

Defaults to the time at which the tag in the configured path was assigned to its current version. Without an explicit start, updates to versions configured by version ID are not spread over time.

Timestamp
percentageoptional
Share of devices that may update, in percent.

Raising the percentage only adds devices. Without duration_secs, it releases the update to the given share right away. With duration_secs, it caps the share of the spread over time.

number
gcoptional
Removal of old versions of the app after an update.

AppGcPolicy
Fields (JSON object)
keepoptional
Number of previously running versions to keep.

Defaults to the integration's default, usually 1.

integer
rolloutoptional
Rollout number.

Integrations ignore its value. Changing it changes the app's configuration, which starts a new round of attempts on devices whose attempts failed.

integer
stateoptional
Current state of the app's update process.

AppUpdateState
Casesexternally
Idle→ "idle"
No path is configured.

Value: "idle"
Installing→ "installing"
A new version is being downloaded and installed without interrupting the app.

Value: "installing"
Activating→ "activating"
The app is switching to the installed version.

Value: "activating"
Removing→ "removing"
The app is being uninstalled.

Value: "removing"
Completed→ "completed"
The app has the target version and its desired state, or it has been uninstalled as desired.

Value: "completed"
Failed→ "failed"
The last attempt failed.

Value: "failed"
Blocked→ "blocked"
An update is available but cannot proceed yet. See blocked for the reason.

Value: "blocked"
blockedoptional
Why the update is blocked. Present when state is blocked.

AppUpdateBlocked
Fields (JSON object)
coderequired
Machine-readable reason in kebab case.

Nexigon defines these codes:

hold: The configuration holds the app at its current version.

spread: The device waits for its turn in a spread or is outside the released percentage.

window: The device waits for its maintenance window. The new version may already be installed.

no-asset: The target version has no bundle for the device's architecture or no available asset with the filename in config.asset.

string
messageoptional
Human-readable explanation.

string
generationoptional
Generation of the app that runs, or that runs when the app starts.

integer (i64)
currentVersionId(from current_version_id)optional
Package version of generation.

Absent when the integration did not install the generation.

PackageVersionIdstring
targetVersionId(from target_version_id)optional
Package version that the configured path resolves to.

PackageVersionIdstring
assetoptional
Filename of the bundle selected from the target version.

string
failureCount(from failure_count)optional
Number of consecutive failed attempts for the target version.

Resets to zero when the target version or the effective configuration of the app changes, when the retry cooldown ends, when an update succeeds, or when another writer clears it.

integer
lastError(from last_error)optional
Error message of the last failure, if any.

string
nextAttemptAt(from next_attempt_at)optional
Earliest time of the next attempt.

Set while the app waits for a spread, a maintenance window, a retry delay, or a retry cooldown.

Timestamp
workloadoptional
Live status of the app's workload, as reported by the runtime.

AppWorkloadStatus
Casesinternally — tag field state
Running→ "running"
The workload runs.

{ "state": "running" }
Unhealthy→ "unhealthy"
The workload runs but reports a problem.

{ "state": "unhealthy", ...<payload fields> } — or "content" for non-object payloads
AppWorkloadMessage
Fields (JSON object)
messagerequired
Human-readable explanation.

string
Stopped→ "stopped"
The workload does not run.

{ "state": "stopped" }
Failed→ "failed"
The workload failed.

{ "state": "failed", ...<payload fields> } — or "content" for non-object payloads
AppWorkloadMessage
Fields (JSON object)
messagerequired
Human-readable explanation.

string
Unknown→ "unknown"
The runtime cannot determine the workload's status.

{ "state": "unknown" }

record

`AppRuntime`

Unstable (feature app_updates)

Runtime that installs and runs apps on a device, such as Rugix Apps.

Fields (JSON object)

namerequired
Name of the runtime, such as rugix.

string
versionoptional
Version of the runtime.

string

record

`AppStatus`

Unstable (feature app_updates)

Status of an app on a device.

Fields (JSON object)

managedrequired
Whether dev.nexigon.apps.config lists the app.

boolean
configoptional
Effective configuration of the app, including the policies that apply to it.
ManagedAppConfig
Fields (JSON object)
pathoptional
Version path in the format <repository>/<package>/<version>.

<version> is a tag or a version ID. A tag tracks the version the tag points to. A version ID pins a single version. Without a path, the integration does not install or update the app and only applies state to an installed app.

string
assetoptional
Filename of the bundle that the device installs from a version.

{arch} stands for the architecture of the device. Defaults to <app>-{arch}.rugixb, or to <app>.rugixb if the version has no bundle for the architecture.

string
stateoptional
Desired state of the app. Defaults to running.

AppDesiredState
Casesexternally
Running→ "running"
The app is installed and its workload runs.

Value: "running"
Stopped→ "stopped"
The app is installed but deactivated, so that its workload does not run, also not after a reboot.

Value: "stopped"
Removed→ "removed"
The app is uninstalled, including its persistent data.

Value: "removed"
holdoptional
Hold the app at its current version.

boolean
windowoptional
Maintenance window restricting when updates of the app are activated.

OtaUpdateWindow
Fields (JSON object)
rangesrequired
Time ranges in which updates can be activated.

An empty list never allows activation.

array<OtaUpdateWindowRange>
Items
OtaUpdateWindowRange
Fields (JSON object)
daysoptional
Days on which the range starts.

Defaults to every day.

array<Weekday>
Items
Weekday
Casesexternally
Monday→ "monday"
Value: "monday"
Tuesday→ "tuesday"
Value: "tuesday"
Wednesday→ "wednesday"
Value: "wednesday"
Thursday→ "thursday"
Value: "thursday"
Friday→ "friday"
Value: "friday"
Saturday→ "saturday"
Value: "saturday"
Sunday→ "sunday"
Value: "sunday"
startrequired
Start of the range (inclusive).

TimeOfDay
Wraps
string
endrequired
End of the range (exclusive).

An end at or before the start lies on the following day. A range whose end equals its start therefore spans 24 hours.

TimeOfDay
Wraps
string
retryoptional
Retry policy for failed update attempts of the app.

OtaUpdateRetryPolicy
Fields (JSON object)
maxAttempts(from max_attempts)optional
Maximum number of failed attempts for a version.

Unlimited when absent.

integer
initialDelaySecs(from initial_delay_secs)optional
Delay before the first retry in seconds.

integer
maxDelaySecs(from max_delay_secs)optional
Maximum delay between attempts in seconds.

integer
cooldownSecs(from cooldown_secs)optional
Time in seconds after reaching max_attempts before the failure count resets and a new round of attempts begins.

Without a cooldown, the device stops attempting the version until the version of the configuration changes or the failure count is cleared.

integer
spreadoptional
Spreading of updates of the app across devices.

OtaUpdateSpread
Fields (JSON object)
durationSecs(from duration_secs)optional
Time over which updates are spread, in seconds.

integer
startAt(from start_at)optional
Start of the spread over time.

Defaults to the time at which the tag in the configured path was assigned to its current version. Without an explicit start, updates to versions configured by version ID are not spread over time.

Timestamp
percentageoptional
Share of devices that may update, in percent.

Raising the percentage only adds devices. Without duration_secs, it releases the update to the given share right away. With duration_secs, it caps the share of the spread over time.

number
gcoptional
Removal of old versions of the app after an update.

AppGcPolicy
Fields (JSON object)
keepoptional
Number of previously running versions to keep.

Defaults to the integration's default, usually 1.

integer
rolloutoptional
Rollout number.

Integrations ignore its value. Changing it changes the app's configuration, which starts a new round of attempts on devices whose attempts failed.

integer
stateoptional
Current state of the app's update process.
AppUpdateState
Casesexternally
Idle→ "idle"
No path is configured.

Value: "idle"
Installing→ "installing"
A new version is being downloaded and installed without interrupting the app.

Value: "installing"
Activating→ "activating"
The app is switching to the installed version.

Value: "activating"
Removing→ "removing"
The app is being uninstalled.

Value: "removing"
Completed→ "completed"
The app has the target version and its desired state, or it has been uninstalled as desired.

Value: "completed"
Failed→ "failed"
The last attempt failed.

Value: "failed"
Blocked→ "blocked"
An update is available but cannot proceed yet. See blocked for the reason.

Value: "blocked"
blockedoptional
Why the update is blocked. Present when state is blocked.
AppUpdateBlocked
Fields (JSON object)
coderequired
Machine-readable reason in kebab case.

Nexigon defines these codes:

hold: The configuration holds the app at its current version.

spread: The device waits for its turn in a spread or is outside the released percentage.

window: The device waits for its maintenance window. The new version may already be installed.

no-asset: The target version has no bundle for the device's architecture or no available asset with the filename in config.asset.

string
messageoptional
Human-readable explanation.

string
generationoptional
Generation of the app that runs, or that runs when the app starts.

integer (i64)
currentVersionId(from current_version_id)optional
Package version of generation.

Absent when the integration did not install the generation.

PackageVersionIdstring
targetVersionId(from target_version_id)optional
Package version that the configured path resolves to.

PackageVersionIdstring
assetoptional
Filename of the bundle selected from the target version.

string
failureCount(from failure_count)optional
Number of consecutive failed attempts for the target version.

Resets to zero when the target version or the effective configuration of the app changes, when the retry cooldown ends, when an update succeeds, or when another writer clears it.

integer
lastError(from last_error)optional
Error message of the last failure, if any.

string
nextAttemptAt(from next_attempt_at)optional
Earliest time of the next attempt.

Set while the app waits for a spread, a maintenance window, a retry delay, or a retry cooldown.

Timestamp
workloadoptional
Live status of the app's workload, as reported by the runtime.
AppWorkloadStatus
Casesinternally — tag field state
Running→ "running"
The workload runs.

{ "state": "running" }
Unhealthy→ "unhealthy"
The workload runs but reports a problem.

{ "state": "unhealthy", ...<payload fields> } — or "content" for non-object payloads
AppWorkloadMessage
Fields (JSON object)
messagerequired
Human-readable explanation.

string
Stopped→ "stopped"
The workload does not run.

{ "state": "stopped" }
Failed→ "failed"
The workload failed.

{ "state": "failed", ...<payload fields> } — or "content" for non-object payloads
AppWorkloadMessage
Fields (JSON object)
messagerequired
Human-readable explanation.

string
Unknown→ "unknown"
The runtime cannot determine the workload's status.

{ "state": "unknown" }

variant

`AppUpdateCapability`

Unstable (feature app_updates)

Optional feature of the app update contract.

Casesexternally

Window→ "window"
The integration honors window.

Value: "window"
Retry→ "retry"
The integration honors retry and resets the failure count of an app when its configuration changes.

Value: "retry"
Spread→ "spread"
The integration honors spread.

Value: "spread"
Hold→ "hold"
The integration honors hold.

Value: "hold"
Asset→ "asset"
The integration honors asset.

Value: "asset"
Gc→ "gc"
The integration honors gc.

Value: "gc"

variant

`AppUpdateState`

Unstable (feature app_updates)

State of an app's update process.

The resting states are idle, completed, failed, and blocked.

Casesexternally

Idle→ "idle"
No path is configured.

Value: "idle"
Installing→ "installing"
A new version is being downloaded and installed without interrupting the app.

Value: "installing"
Activating→ "activating"
The app is switching to the installed version.

Value: "activating"
Removing→ "removing"
The app is being uninstalled.

Value: "removing"
Completed→ "completed"
The app has the target version and its desired state, or it has been uninstalled as desired.

Value: "completed"
Failed→ "failed"
The last attempt failed.

Value: "failed"
Blocked→ "blocked"
An update is available but cannot proceed yet. See blocked for the reason.

Value: "blocked"

record

`AppUpdateBlocked`

Unstable (feature app_updates)

Information about a blocked app update.

Fields (JSON object)

coderequired
Machine-readable reason in kebab case.

Nexigon defines these codes:
- hold: The configuration holds the app at its current version.
- spread: The device waits for its turn in a spread or is outside the released percentage.
- window: The device waits for its maintenance window. The new version may already be installed.
- no-asset: The target version has no bundle for the device's architecture or no available asset with the filename in config.asset.
string
messageoptional
Human-readable explanation.

string

variant

`AppWorkloadStatus`

Unstable (feature app_updates)

Live status of an app's workload.

Casesinternally — tag field state

Running→ "running"
The workload runs.

{ "state": "running" }
Unhealthy→ "unhealthy"
The workload runs but reports a problem.

{ "state": "unhealthy", ...<payload fields> } — or "content" for non-object payloads
AppWorkloadMessage
Fields (JSON object)
messagerequired
Human-readable explanation.

string
Stopped→ "stopped"
The workload does not run.

{ "state": "stopped" }
Failed→ "failed"
The workload failed.

{ "state": "failed", ...<payload fields> } — or "content" for non-object payloads
AppWorkloadMessage
Fields (JSON object)
messagerequired
Human-readable explanation.

string
Unknown→ "unknown"
The runtime cannot determine the workload's status.

{ "state": "unknown" }

record

`AppWorkloadMessage`

Unstable (feature app_updates)

Explanation of an app's workload status.

Fields (JSON object)

messagerequired
Human-readable explanation.

string

Edit this page

PreviousAudit Logging NextDevices

App Updates

Interface

Configuration Property

Bundle Selection

Check Cycle

Old Versions

Status Property

States

Blocked Codes

Requesting a Retry

Sidex Schema

schemaproperties

schema`properties`