Edge Runtime Update Specification

1. Goal

Edge Runtime updates must be safe, auditable, and compatible with both manual operations and managed rollout.

The update system must support:

• manual host-side updates.
• automatic updates controlled by local and Control Plane policy.
• package-manager based installation and updates.
• standalone binary fallback for unsupported Linux distributions.
• rollback when the updated daemon fails to start.
• clean separation between user CLI and long-running daemon.

2. Process Model

Long-term process names:

orbitmesh      local CLI
orbitmeshd     long-running Edge Runtime daemon
orbitmeshd.service

orbitmeshd owns:

• device identity.
• Control Plane request signing.
• heartbeat.
• Desired State sync.
• runtime configuration apply.
• runtime health and metrics.
• automatic update checks.
• update result reporting.

orbitmesh owns:

• local status commands.
• manual update commands.
• up, login, logout, and down commands that ask the daemon to manage local session state.
• local diagnostics.
• local daemon control through a Unix socket.

3. Local IPC

The CLI talks to the daemon through a root-owned Unix socket:

/run/orbitmesh/orbitmeshd.sock

Rules:

• daemon creates the socket at startup.
• socket owner is root.
• group may be orbitmesh when non-root CLI access is supported.
• CLI must not directly modify /var/lib/orbitmesh/edge-runtime/identity.key.
• privileged operations such as update, enroll, reset, and service restart require root unless explicitly delegated later.

Initial local API:

GET  /local/v1/status
GET  /local/v1/version
POST /local/v1/login
POST /local/v1/logout
POST /local/v1/down
POST /local/v1/update/check
POST /local/v1/update/apply

This API is local only. It must not listen on TCP.

4. Manual Commands

Target CLI:

orbitmesh version
orbitmesh version --upstream
orbitmesh status
orbitmesh up
orbitmesh login --control-plane-url https://api.orbitmesh.dev --deployment-token TOKEN
orbitmesh down
orbitmesh logout
orbitmesh update --check
sudo orbitmesh update --yes
sudo orbitmesh update --version v0.1.8
sudo orbitmesh update --channel stable
sudo orbitmesh set --auto-update=true
sudo orbitmesh set --auto-update=false
sudo orbitmesh debug logs

Command behavior:

• version prints CLI, daemon, runtime, update channel, and install method.
• version --upstream also checks the selected release channel manifest.
• status prints daemon identity, operator state, runtime status, applied configuration version, and the latest heartbeat/sync timestamps and errors.
• up enables an already registered device, or enrolls it when a deployment token is supplied. When a disabled device is re-enabled, the daemon resets the applied version cursor and immediately requests a sync so the current Desired State is reapplied.
• login enrolls or re-enrolls the device through orbitmeshd.
• down asks orbitmeshd to stop the local runtime, disables OrbitMesh control-plane interaction locally, and keeps the device binding.
• logout asks orbitmeshd to stop the local runtime, clears the local node and edge-runtime binding, and preserves the installation identity.
• update --check downloads metadata only and prints the candidate version.
• update --yes applies the latest allowed candidate.
• update --version pins a versioned release and skips channel selection.
• update --track changes the update channel before checking.
• set --auto-update persists local policy and asks the daemon to reload it.

The CLI should return non-zero when:

• no daemon is reachable for daemon-backed commands.
• the host is not registered.
• the update source is unsupported.
• checksum or signature verification fails.
• package-manager update fails.
• daemon restart verification fails.

5. Install Method

Every installation records its update method:

/var/lib/orbitmesh/edge-runtime/install.json

Shape:

{
  "install_method": "standalone",
  "package_manager": "",
  "channel": "stable",
  "auto_update_enabled": false,
  "installed_at": "2026-06-18T00:00:00Z",
  "current_version": "v0.1.8",
  "previous_version": "",
  "last_update_status": "none",
  "last_update_error": ""
}

Supported install_method values:

standalone
package
container

Rules:

• standalone uses release manifests and direct binary downloads.
• package uses the detected system package manager.
• container does not self-update; it reports available updates and lets the deployment platform replace the image.

6. Release Channels

Supported channels:

stable
unstable
candidate

Default:

stable

Channel URLs:

https://downloads.orbitmesh.dev/edge-runtime/stable/manifest.json
https://downloads.orbitmesh.dev/edge-runtime/unstable/manifest.json
https://downloads.orbitmesh.dev/edge-runtime/candidate/manifest.json

Versioned URLs:

https://downloads.orbitmesh.dev/edge-runtime/v0.1.8/manifest.json

The historical latest path may remain as a compatibility download alias, but update code must use manifests.

7. Release Manifest

Manifest example:

{
  "schema_version": 1,
  "component": "edge-runtime",
  "version": "v0.1.8",
  "channel": "stable",
  "released_at": "2026-06-18T00:00:00Z",
  "min_control_plane_version": "v0.1.8",
  "critical": false,
  "files": [
    {
      "os": "linux",
      "arch": "amd64",
      "kind": "tar",
      "url": "https://downloads.orbitmesh.dev/edge-runtime/v0.1.8/orbitmesh-edge-runtime-linux-amd64.tar.gz",
      "sha256": "hex",
      "signature": "base64url"
    }
  ],
  "packages": {
    "apt": {
      "repo": "https://pkgs.orbitmesh.dev/stable/apt",
      "package": "orbitmesh",
      "version": "0.1.8"
    },
    "rpm": {
      "repo": "https://pkgs.orbitmesh.dev/stable/rpm",
      "package": "orbitmesh",
      "version": "0.1.8"
    }
  }
}

Rules:

• manifest is immutable at versioned paths.
• channel manifests point at the latest approved release for that channel.
• artifact SHA-256 must be verified before install.
• artifact signature must be verified before install once signing keys are introduced.
• release metadata should be served with short cache TTL on channel paths and long immutable cache TTL on versioned paths.

8. Standalone Layout

Standalone installs use versioned directories and atomic symlink switching:

/opt/orbitmesh/versions/v0.1.8/orbitmesh
/opt/orbitmesh/versions/v0.1.8/orbitmeshd
/opt/orbitmesh/current -> /opt/orbitmesh/versions/v0.1.8
/usr/local/bin/orbitmesh -> /opt/orbitmesh/current/orbitmesh
/usr/local/bin/orbitmeshd -> /opt/orbitmesh/current/orbitmeshd

Update flow:

1. Acquire local update lock.
2. Download manifest.
3. Select file by OS and architecture.
4. Download artifact to staging directory.
5. Verify checksum and signature.
6. Extract to /opt/orbitmesh/versions/$version.
7. Run orbitmeshd version as a smoke check.
8. Switch /opt/orbitmesh/current symlink atomically.
9. Run systemctl daemon-reload.
10. Restart orbitmeshd.service.
11. Verify daemon version and health.
12. Persist update result.
13. Report update result to Control Plane.

Rollback flow:

1. If restart or health verification fails, switch symlink back to previous version.
2. Restart orbitmeshd.service.
3. Persist failed update result.
4. Report failure to Control Plane.
5. Put the failed version into local cooldown.

The updater must never delete the previous version during the same update transaction.

9. Package Manager Layout

Primary package:

orbitmesh

Package contents:

/usr/bin/orbitmesh
/usr/sbin/orbitmeshd
/lib/systemd/system/orbitmeshd.service
/etc/default/orbitmeshd
/usr/share/doc/orbitmesh/

Debian and Ubuntu:

apt

RPM-based distributions:

dnf
yum
zypper

Package-manager update flow:

1. Detect recorded package manager.
2. Refresh repository metadata.
3. Install requested package version or upgrade to channel candidate.
4. Restart orbitmeshd.service if the package manager did not do so.
5. Verify daemon version and health.
6. Persist and report result.

Rules:

• package installs must not overwrite device identity.
• package post-install may create users, directories, and service units.
• package post-install must not enroll the host automatically without a deployment token.
• package post-remove must not delete identity unless purge semantics are explicitly requested.

10. Installer Behavior

install.orbitmesh.dev should prefer package-manager installation when supported:

1. Detect Linux distribution.
2. Detect package manager.
3. Configure OrbitMesh package repository.
4. Install the orbitmesh package.
5. Run enrollment with the provided deployment token.
6. Start orbitmeshd.service.

Fallback:

• if the distribution is unsupported, use standalone install.
• if ORBITMESH_INSTALL_METHOD=standalone, force standalone install.
• if ORBITMESH_INSTALL_METHOD=package, fail instead of falling back when package installation is unsupported.

Environment variables:

ORBITMESH_DEPLOYMENT_TOKEN
ORBITMESH_CONTROL_PLANE_URL
ORBITMESH_INSTALL_METHOD
ORBITMESH_UPDATE_CHANNEL
ORBITMESH_AUTO_UPDATE
ORBITMESH_EDGE_RUNTIME_DOWNLOAD_PREFIX
ORBITMESH_CLI_DOWNLOAD_URL
ORBITMESH_DAEMON_DOWNLOAD_URL
ORBITMESH_PACKAGE_REPO_URL

11. Automatic Update Policy

Policy sources, highest priority first:

1. local explicit disable.
2. Control Plane node policy.
3. tenant default policy.
4. installer default.

Policy fields:

{
  "mode": "manual",
  "channel": "stable",
  "target_version": "",
  "maintenance_window": "",
  "rollout_group": "",
  "max_unavailable": 1
}

Supported mode values:

disabled
manual
automatic
security_only

Default:

manual

Rules:

• disabled blocks automatic and Control Plane initiated updates.
• manual allows local orbitmesh update.
• automatic allows daemon scheduled updates.
• security_only allows only releases marked critical=true.
• local explicit disable wins over Control Plane policy.

12. Automatic Update Loop

Daemon loop:

timer with jitter
  |
load local install state
  |
pull Control Plane update policy
  |
resolve release channel manifest
  |
compare versions
  |
check rollout eligibility
  |
apply update
  |
report result

Default interval:

6h

Jitter:

0-30m

Preconditions:

• host is enrolled.
• no runtime configuration apply is in progress.
• no update lock is held.
• target version is not in cooldown.
• Control Plane compatibility check passes.
• current package manager or standalone updater is available.

13. Control Plane API

Edge Runtime API additions:

GET  /api/v1/edge-runtime/update-policy
POST /api/v1/edge-runtime/update-result

UpdatePolicyResponse:

{
  "mode": "manual",
  "channel": "stable",
  "target_version": "",
  "manifest_url": "https://downloads.orbitmesh.dev/edge-runtime/stable/manifest.json",
  "min_version": "",
  "max_version": "",
  "rollout_allowed": true
}

UpdateResultRequest:

{
  "node_id": "uuid",
  "from_version": "v0.1.7",
  "to_version": "v0.1.8",
  "install_method": "standalone",
  "status": "applied",
  "error": "",
  "started_at": "2026-06-18T00:00:00Z",
  "finished_at": "2026-06-18T00:01:00Z"
}

Heartbeat additions:

{
  "install_method": "standalone",
  "update_channel": "stable",
  "auto_update_enabled": false,
  "latest_available_version": "v0.1.8",
  "update_status": "applied",
  "last_update_error": ""
}

All update API requests use the existing Edge Runtime request signing.

14. Console

Node detail should show:

• installed Edge Runtime version.
• latest stable version.
• update channel.
• install method.
• auto-update mode.
• last update status.
• last update error.
• last update time.

Actions:

• enable or disable automatic updates.
• select channel.
• request update to latest.
• request update to a pinned version.

MVP can defer Console actions and show read-only status first.

15. Release Workflow

Edge Runtime release must publish:

orbitmesh-linux-amd64
orbitmesh-linux-arm64
orbitmeshd-linux-amd64
orbitmeshd-linux-arm64
SHA256SUMS
manifest.json

The commands object maps each executable to OS and architecture specific artifacts:

{
  "commands": {
    "orbitmesh": [],
    "orbitmeshd": []
  }
}

Package release should publish:

orbitmesh_$VERSION_linux_amd64.deb
orbitmesh_$VERSION_linux_arm64.deb
orbitmesh-$VERSION-1.x86_64.rpm
orbitmesh-$VERSION-1.aarch64.rpm

Repository metadata:

apt Release/InRelease/Packages
rpm repodata/

Signing:

• tar artifacts are signed through manifest signatures.
• apt repository metadata is signed with OrbitMesh package signing key.
• rpm packages are signed with OrbitMesh RPM signing key.

16. Service Unit

Target service:

[Unit]
Description=OrbitMesh Edge Runtime Daemon
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/sbin/orbitmeshd --config /etc/orbitmesh/edge-runtime.yaml
Restart=always
RestartSec=5
User=root
Group=root
LimitNOFILE=1048576

[Install]
WantedBy=multi-user.target

Standalone installs may use:

/usr/local/bin/orbitmeshd

Package installs should use:

/usr/sbin/orbitmeshd

17. Safety Requirements

• Do not update while runtime config apply is active.
• Do not delete previous version until the new version has been healthy for at least one update interval.
• Do not rewrite device identity during update.
• Do not print deployment tokens or private keys.
• Do not trust unsigned manifests once signing is enabled.
• Do not auto-update across declared incompatible Control Plane ranges.
• Do not auto-update container installs.

18. MVP Phases

Phase 1:

• introduce release manifest.
• add standalone orbitmesh update --check.
• publish command-specific artifacts.

Current development implementation:

• release workflow publishes manifest.json to the versioned path, latest, and stable.
• release workflow publishes orbitmesh and orbitmeshd Linux artifacts.
• orbitmesh update --check asks orbitmeshd to check CLI and daemon artifacts from the release manifest.
• orbitmesh update --yes asks orbitmeshd to download selected artifacts, verify SHA-256, replace orbitmesh and orbitmeshd, and restart orbitmeshd.service.
• orbitmeshd does not expose a user-facing update command.

Phase 2:

• add standalone manual update apply.
• add atomic versioned install layout.
• add rollback on failed daemon restart.

Phase 3:

• split orbitmesh CLI and orbitmeshd daemon.
• add local Unix socket API.

Current Phase 3 status:

• orbitmesh and orbitmeshd binaries are built from shared command code.
• orbitmeshd starts a local Unix socket API at /run/orbitmesh/orbitmeshd.sock; run remains accepted for existing service units and tests.
• orbitmesh up, orbitmesh status, orbitmesh version --daemon, and orbitmesh update use the local Unix socket API.
• orbitmesh update is the only user-facing manual update command.
• orbitmeshd remains a background daemon and exposes only daemon lifecycle commands.

Phase 4:

• add Control Plane update policy and update result API.
• add automatic update loop.

Phase 5:

• add Debian package and apt repository.
• update installer to prefer package installation.

Phase 6:

• add RPM packages and repository metadata.
• add Console update controls.