• 1:
• 2:
• 3:
• 4:
• 5:
• 6:
• 7:

1 -

OS upgrades

You upgrade a device’s operating system by setting the OS version you want; the device downloads the new version, switches to it, and reboots. Because the system image is separate from your configuration and data, your setup is preserved across the change, and you can roll back to a previous version.

How upgrades work

1. You set the target OS version for a device (or a group of devices) from the dashboard.
2. The device downloads the requested version and prepares it alongside the current one.
3. The device switches to the new version and reboots.
4. After reboot, the device reports its new version, and your configuration and data are intact.

A device keeps more than one OS version on disk — the one it is running and the one it can fall back to — which is what makes switching versions and rolling back fast and safe.

Release channels and compatibility

• OS versions are published per device type, so a device is only offered versions compatible with its hardware.
• Some upgrades may require a minimum current version before you can move to the target, to ensure a supported upgrade path.

Rolling back

If a new version misbehaves, you can roll a device back to the version it was running before, or to its original factory version. Because the previous version is retained on the device, rollback does not require re-downloading it.

Set the desired (earlier) version the same way you set an upgrade; the device switches back and reboots.

Encrypted devices

Managed upgrades preserve automatic unlock on encrypted devices — no manual action is required to keep an encrypted device unlocking across an upgrade.

If an upgrade does not complete

• Confirm the device has connectivity to download the new version (including through any proxy).
• A device that fails to start a new version can fall back to the retained previous version.
• See the troubleshooting playbooks for upgrade issues.

2 -

Reboot, shutdown & recovery

This page covers power actions you can take remotely and the options for recovering a device that is not behaving as expected.

Reboot and shutdown

You can reboot or shut down a device remotely from the dashboard or with the cuttle command-line tool. These actions are carried over the device’s connection to the platform and require no inbound access to the device.

A device that loses power or is reset returns to its configured state on next boot, because configuration and data are persistent and the system image is read-only.

Automatic recovery

The OS is designed to keep itself running unattended:

• It restarts automatically after an unexpected fault rather than waiting at an error.
• Workloads configured to run are brought back up after a reboot.
• If a network configuration change does not produce a working connection, the device can fall back to known-good network settings — see connection fallback.

Recovery options

When a device needs hands-on recovery, the options in increasing order of impact:

See User accounts for password reset and Disk encryption for encrypted-device recovery.

When a device is offline

If a device is offline and unreachable through the platform, work through the troubleshooting playbooks — most often the cause is connectivity, time, or a network configuration change.

3 -

Logging

Devices can forward their logs to the SPEKTRA Edge platform and you can also pull logs on demand. This lets you observe devices and workloads without logging into each one.

Forwarding logs to the platform

You can configure a device to forward its system logs and its container (workload) logs to the platform. The logging configuration lets you control:

• the minimum severity to forward, so you can keep volume manageable
• which system components to include
• whether container logs are exported

Forwarded logs are available on the dashboard and through the cuttle command-line tool.

Pulling logs on demand

Independently of forwarding, you can stream a device’s system or container logs on demand through remote access — useful for live troubleshooting without raising the forwarding level for the whole fleet.

Recommendations

• Forward at a moderate severity by default and raise it temporarily when investigating an issue.
• Use on-demand log streaming for live debugging rather than forwarding everything.
• Remember that logs stored on the device live on the data area; very verbose logging consumes data-area space.

4 -

Health checks

Health checks let a device continuously verify that it — or something running on it — is healthy, and report the result to the platform. You define health checks from the dashboard (or the API).

Types of checks

You can define host-level checks of several types:

How results are used

Each check’s result contributes to the device’s reported conditions, which you can see on the device overview page. Use health checks to detect problems such as a dependent service being unreachable, a required peripheral missing, or a local endpoint failing — and to surface them centrally instead of discovering them per device.

Recommendations

• Check the things that matter for the device’s role (for example, the local application endpoint, or a sensor’s device file).
• Keep checks lightweight and give them sensible intervals so they reflect real health without adding load.

5 -

Status & indicators

A device reports its state both to the platform and, on supported hardware, through a physical LED. This page explains how to read each.

Connection status

On the platform, a device is shown as:

Device information and metrics

The device reports details and resource usage you can view on the dashboard, including:

• OS version, hardware details, disks, and network interfaces
• CPU, memory, and storage usage
• temperature

These help you spot devices that are low on storage, running hot, or pinned at high resource usage.

LED indicator

On hardware with a status LED, the device signals its lifecycle and health through the LED so an on-site technician can tell at a glance what state a device is in — for example, still starting up, working normally, or needing attention. Use the LED for quick on-site triage, and the dashboard for detail.

Conditions from health checks

Health checks you define contribute to the device’s reported conditions, giving you application- and peripheral-level health alongside the built-in status.

6 -

Boot & shutdown hooks

Hooks let you run your own scripts at defined points in the device lifecycle — for example to prepare hardware, mount a special device, or clean up on shutdown. They are the supported way to extend device behavior without modifying the read-only system image.

Available hooks

You can provide a script for each of these points:

How to provide a hook

Place an executable script in the hooks location on the device’s configuration storage. Because it lives on configuration storage, the script persists across reboots and OS upgrades and is run automatically at the corresponding point. See the persistent paths reference for the exact location.

Guidelines

• Keep hooks fast and resilient. A slow or failing boot hook delays startup; make hooks idempotent and have them exit cleanly.
• Do not rely on modifying the system image. Use hooks to act on configuration and data, not to patch the OS — image changes do not persist.
• Log from your hook so you can see what it did via logging.
• Test on one device first before distributing a hook to a fleet.

7 -

Running workloads

Devices run your applications as containers. You deploy and manage them from the SPEKTRA Edge platform; this page covers only how workloads interact with the OS. For the full application deployment workflow, see the Deploy guide.

How workloads use device storage

• Container images and workload data live on the device’s data area, which uses most of the disk.
• A workload can mount paths from the device into its containers when it needs access to host data or hardware.
• Credentials a workload needs (such as registry pull secrets) are delivered through the platform rather than stored in the image.

Networking for workloads

• Any network ports a workload exposes are determined by the workload itself, not by the OS — open them in your site firewall as needed. See Connectivity & ports.
• Workload traffic honors the device’s proxy configuration.

When storage runs low

Because container images and data share the data area, a device that fills its data area can fail to start new workloads. Watch storage usage in device metrics, and keep logging levels reasonable so logs do not consume the space your workloads need.

Lifecycle across reboots and upgrades

Workloads configured to run are brought back up after a reboot, and persist across OS upgrades because their images and data are on persistent storage.