Skip to documentation
OrbitMeshDocs
Browse documentation
Docs/Engineering Specs

ENGINEERING SPECS

Edge Runtime Installer Specification

The installer turns a supported Linux host into an OrbitMesh Node.
View source

1. Goal

The installer turns a supported Linux host into an OrbitMesh Node.

The install target is the orbitmesh CLI plus the orbitmeshd daemon.

2. Install Commands

curl -fsSL https://install.orbitmesh.dev | \
  sudo env ORBITMESH_DEPLOYMENT_TOKEN=om_dt_xxx sh

Control Plane generates this command when a deployment token is created. The command uses the configured install endpoint URL, deployment token, Control Plane URL, and artifact download prefix. The public install endpoint should stay pathless for the default Edge Runtime installer.

The script has production defaults for ORBITMESH_CONTROL_PLANE_URL and ORBITMESH_EDGE_RUNTIME_DOWNLOAD_PREFIX. Runtime dependency details are pulled and executed by orbitmeshd after enrollment, not by the installer. ORBITMESH_DEPLOYMENT_TOKEN is required only when the host is not already enrolled or when forced re-enrollment is requested.

3. Script Responsibilities

The script must:

  1. Check root.
  2. Detect OS.
  3. Detect architecture.
  4. Detect package manager.
  5. Resolve install method.
  6. Install OrbitMesh through package manager when supported.
  7. Fall back to standalone binary install when configured or required.
  8. Register with Control Plane when the host is not already enrolled.
  9. Write Edge Runtime config files.
  10. Install the orbitmeshd systemd unit.
  11. Start orbitmeshd.
  12. Resume the local daemon session so it can pull desired state.
  13. Report result.

4. Supported Systems

MVP:

  • Ubuntu 22.04.
  • Ubuntu 24.04.
  • Debian 12.

5. Directory Layout

Package layout:

/usr/bin/orbitmesh
/usr/sbin/orbitmeshd
/etc/orbitmesh/edge-runtime.yaml
/var/lib/orbitmesh/edge-runtime/identity.json
/var/lib/orbitmesh/edge-runtime/identity.key
/lib/systemd/system/orbitmeshd.service
/etc/default/orbitmeshd
/etc/orbitmesh/runtime-configs/$RUNTIME.json

Standalone layout:

/opt/orbitmesh/versions/$VERSION/orbitmesh
/opt/orbitmesh/versions/$VERSION/orbitmeshd
/opt/orbitmesh/current
/usr/local/bin/orbitmesh
/usr/local/bin/orbitmeshd

6. Artifact Delivery

The installer does not query the source repository and does not depend on GitHub Release assets. Edge Runtime binaries are published to object storage and optionally served through a CDN. Cloudflare R2 is the default object store; AWS S3 is also supported.

Release artifact names are stable:

orbitmesh-linux-amd64
orbitmesh-linux-arm64
orbitmeshd-linux-amd64
orbitmeshd-linux-arm64

The release workflow uploads each build to a versioned path and to a stable latest channel:

s3://$BUCKET/$PREFIX/v0.1.0/orbitmesh-linux-amd64
s3://$BUCKET/$PREFIX/v0.1.0/orbitmesh-linux-arm64
s3://$BUCKET/$PREFIX/v0.1.0/orbitmeshd-linux-amd64
s3://$BUCKET/$PREFIX/v0.1.0/orbitmeshd-linux-arm64
s3://$BUCKET/$PREFIX/latest/orbitmesh-linux-amd64
s3://$BUCKET/$PREFIX/latest/orbitmesh-linux-arm64
s3://$BUCKET/$PREFIX/latest/orbitmeshd-linux-amd64
s3://$BUCKET/$PREFIX/latest/orbitmeshd-linux-arm64

Production Control Plane config defaults to the public install service and object storage or CDN latest prefix:

ORBITMESH_INSTALL_ENDPOINT_URL=https://install.orbitmesh.dev
ORBITMESH_EDGE_RUNTIME_DOWNLOAD_PREFIX=https://downloads.orbitmesh.dev/edge-runtime/latest

This keeps Control Plane configuration stable across releases. A fixed version can still be selected by pointing the prefix at a versioned path.

Object ACLs are not required. Public download access should be provided by the bucket policy, R2 custom domain, or CDN in front of the bucket.

Update-aware releases must also publish immutable manifests and channel manifests:

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

The installer uses the latest path for initial installation. Manual and automatic update code must use the manifest format defined in edge-runtime-update.md.

7. Package Manager Installation

The installer should prefer package-manager installation when supported.

Supported first:

  • apt on Ubuntu and Debian.

Supported later:

  • dnf.
  • yum.
  • zypper.

Rules:

  • ORBITMESH_INSTALL_METHOD=package requires package-manager installation and fails if unsupported.
  • ORBITMESH_INSTALL_METHOD=standalone forces direct binary installation.
  • unset ORBITMESH_INSTALL_METHOD uses package manager when supported, otherwise standalone.
  • package install must not enroll without ORBITMESH_DEPLOYMENT_TOKEN.
  • package install must not remove existing identity.

8. Runtime Install Profiles

Runtime dependency installation is table-driven, but it is owned by orbitmeshd, not by the installer. Control Plane stores runtime install profiles in tables and returns them through desired state. The daemon matches profiles to runtime bindings, installs required components, writes runtime-owned systemd units, runs verification commands, and reports install/apply status back to Control Plane.

Installer rules:

  • The installer must not parse runtime_install_profiles.
  • The installer must not contain runtime-specific download, archive, binary, service, or config defaults.
  • The installer must not unpack runtime archives.
  • The installer may pass generic daemon settings such as adapter, state dir, socket path, and runtime config path for local smoke tests.

Daemon rules:

  • ORBITMESH_EDGE_ADAPTER=file skips runtime dependency installation.
  • runtime versions, package names, download URL templates, archive formats, archive member templates, component binaries, service names, and runtime config paths come from the install profile.
  • archive_format supports zip, tar, tar.gz or tgz, tar.xz or txz, tar.bz2 or tbz2 or tbz, and tar.zst or tzst.
  • unsupported install methods must fail explicitly.
  • profile checksums must be verified when present.
  • systemd unit content must be generated from profile templates, not runtime-specific daemon branches.

9. Failure Handling

If install fails:

  • Print failed step.
  • Report deploy result if possible.
  • Do not leave partial systemd service enabled.
  • Do not print deployment token.

10. Registration

The installer runs:

orbitmesh up \
  --control-plane-url "$ORBITMESH_CONTROL_PLANE_URL" \
  --deployment-token "$ORBITMESH_DEPLOYMENT_TOKEN"

The Edge Runtime writes:

  • node id.
  • edge runtime id.
  • device identity files.
  • control plane URL.

11. Security

  • identity.key contains the Edge Runtime private key and must not be world-readable.
  • edge-runtime.yaml must not contain long-lived shared secrets.
  • owner: root.
  • deployment token never written to disk after registration.
  • logs redact token-like strings.

12. systemd

See:

deployments/systemd/orbitmeshd.service

Unit:

orbitmeshd.service

See edge-runtime-update.md for daemon naming, standalone layout, package layout, and update behavior.

OrbitMesh DocumentationContent follows the repository's main branch.