• 1:
• 2:
• 3:
• 4:
• 4.1:
• 4.2:
• 4.3:
• 4.4:
• 5:
• 5.1:
• 5.2:
• 5.3:
• 5.4:
• 5.5:
• 5.6:
• 5.7:
• 6:
• 6.1:
• 6.2:
• 6.3:
• 6.4:
• 6.5:
• 6.6:
• 6.7:
• 7:
• 7.1:
• 7.2:
• 7.3:
• 7.4:
• 7.5:
• 8:

1 -

Overview

This section explains the ideas you need before configuring a device: how the OS is structured, how persistence works, and which platforms are supported.

A managed, reconciled operating system

SPEKTRA Edge OS is designed to be operated remotely and at scale. Instead of logging into each device to make changes by hand, you describe the desired state of a device on the SPEKTRA Edge platform, and the device continuously reconciles itself to match. This is the same model whether you manage one device or thousands.

Two consequences are worth keeping in mind from the start:

• The system runs from a read-only image. The core operating system is not meant to be modified in place. This keeps every device in a known, consistent state and makes upgrades and rollback reliable.
• Your configuration and data live on separate, persistent storage. Anything you need to keep across reboots is stored outside the system image.

How persistence works

Understanding what persists is the single most useful thing to know about the OS, because it explains why some changes “disappear” and others stick.

There are three kinds of storage on a device:

The practical rules that follow:

• Ad-hoc changes to the live system do not persist. If you log into a device and edit a file that belongs to the system image, your change is gone after the next reboot. This is intentional.
• To make a durable change, use the configuration mechanisms described in this guide — the dashboard/API for most settings, and files in the configuration area for the rest.
• Upgrades and rollback are safe by design. Because the system image is swapped as a unit while your configuration and data are preserved, you can move between OS versions without losing your setup. See OS upgrades.

Supported platforms

SPEKTRA Edge OS runs on two hardware families. When you create an image or register hardware, the platform is identified by its device type, which combines the hardware family with the CPU architecture.

The device type determines which OS images are compatible with a given device. You select it when creating an install image and when pinning an OS version.

Next steps

Continue with device setup & provisioning to bring hardware online, or jump to the area you need from the guide overview.

2 -

Device setup & provisioning

This section takes a device from blank hardware to a managed device: creating an install image, onboarding the device so it joins your project, setting the administrator password, and confirming it is online.

Setup at a glance

1. Create an install image for the target device type, with the defaults you want baked in (encryption, network, storage, time).
2. Write the image to installation media and boot the device from it.
3. Onboard the device so it obtains an identity and joins your project.
4. Set the administrator password for local and console access.
5. Verify the device is online on the dashboard.

The rest of this page covers each step.

Create an install image

You create install images from the SPEKTRA Edge dashboard. When you create an image you choose:

• the device type (hardware family and architecture) — see supported platforms
• the OS version to install
• default configuration to embed in the image, such as disk encryption, storage mapping, network configuration, time synchronization, and proxy settings
• provisioning credentials, so the device can onboard automatically on first boot (see onboarding methods below)

The values you embed at image creation become the device’s initial configuration. Almost all of them can be changed later from the dashboard once the device is online — the image just provides sensible starting defaults so a device is useful the moment it boots.

Write the image and boot

Write the downloaded image to your installation media, then boot the target hardware from that media. The device boots into SPEKTRA Edge OS, applies the embedded configuration, and begins onboarding.

Onboarding methods

Onboarding is how a device obtains its identity and joins your project. There are three approaches; choose based on how much you want to pre-arrange versus letting devices self-register.

Zero-touch provisioning

With zero-touch provisioning, a device that has never been configured can find the right SPEKTRA Edge deployment, prove its hardware identity, and receive its credentials automatically — no per-device setup required. This is the preferred method for large fleets and for hardware that is shipped directly to a site.

Zero-touch provisioning relies on the device’s hardware security module to establish a trustworthy identity. See TPM & device attestation for how that identity is verified.

Provisioning policy

A provisioning policy lets devices self-register into a project using a shared credential and a template that describes how each new device should be configured. Policies operate in one of two modes:

The policy template carries the desired device configuration (network, SSH, logging, and so on), so every device created through the policy starts from the same baseline.

Pre-registering hardware

You can pre-register specific hardware ahead of time and bind it to a provisioning target. A field technician can then bring the hardware online using a registration token without needing project credentials in hand. This is useful when installation is performed by someone who should not have broad access to the project.

Set the administrator password

Each device has a local administrator account used for console and SSH access. For security, devices ship without a usable default password — you set the password yourself.

You can set the administrator password:

• at image creation, so it applies to every device built from that image, or
• when preparing installation media, on a per-device basis.

The password must be non-empty, and it is stored only as a salted hash on the device’s configuration storage. See User accounts for details and for how to reset a lost password.

Verify the device is online

Once the device boots and onboards, it appears in the dashboard under your project. A device is Online when the platform detects it as connected.

On the device overview page you can confirm:

• connection status (Online / Offline)
• device information — OS version, hardware details, disks, and network interfaces
• reported IP addresses

If a device does not come online, start with the connectivity requirements and the troubleshooting playbooks.

Next steps

With the device online, configure it for your use case:

• set up storage
• configure networking
• review and tighten security

3 -

Storage

This section describes how device storage is laid out by default and how to add your own partitions and mounts or expand storage to use the whole disk.

Default disk layout

A device’s primary disk is divided into a small number of areas, each with a distinct role:

The data area takes the remaining space on the disk, so most of the disk is available to your workloads. The configuration and data areas hold everything you set up; the boot and system-image areas belong to the OS and are managed for you across upgrades.

Configuring additional partitions and mounts

You can attach extra storage and control where it is mounted using a storage mapping. The mapping is a YAML document that lists the partitions a device should ensure exist and where each should be mounted, plus any bind mounts that redirect a directory to persistent storage.

You can provide the storage mapping when you create an install image (so it applies from first boot) or push it from the dashboard.

Mapping format

A storage mapping has two sections: diskmappings (partitions to ensure and mount) and bindmounts (directories to redirect).

diskmappings:
  - disk: /dev/sdb
    partition_number: 1
    mountpoint: /mnt/extra
    size: 50G
    filesystem: ext4
  - disk: /dev/sdb
    partition_number: 2
    mountpoint: /mnt/scratch
    size: -1            # use all remaining free space
    filesystem: ext4

bindmounts:
  - mountsource: /mnt/extra/registry
    mountpoint: /var/lib/registry

The fields for each diskmappings entry:

Behavior to keep in mind:

• If a partition already exists, it is mounted as specified; size and filesystem are ignored (existing data is not reformatted).
• If a partition does not exist and there is room, it is created with the requested size and filesystem, then mounted.
• A partition with size: -1 grows to fill the free space available on its disk.

Logical mount names

For convenience, a few common destinations can be referenced by name instead of an absolute path:

Bind mounts

A bind mount redirects a directory onto persistent storage so its contents survive reboots and upgrades. By default, the standard runtime directories (container storage, logs, and the agent’s working directory) are already bound to the data area; add your own entries only when you want additional directories to persist or to live on a separate disk.

Expanding storage

When you install onto a disk that is larger than the image, the data area can be grown to use the extra space:

• During installation you can request that the last partition be expanded to fill the disk.
• A storage mapping entry with size: -1 grows the data partition to consume the remaining free space.

This lets a single image target disks of different sizes while still using all available capacity for workloads and data.

Next steps

• Turn on disk encryption to protect the configuration and data areas.
• Configure networking for the device.

4 -

Networking

This section covers how a device connects to the network and to the SPEKTRA Edge platform: how you describe network configuration, how the device falls back between connections, how to route through a proxy, what the device needs to reach on the network, and how time is kept in sync.

• Network configuration model
• Connection fallback
• Proxy configuration
• Connectivity & ports
• Time synchronization

Network configuration model

Device networking is described as a Netplan-format YAML document. This is a clean, declarative way to configure wired, Wi-Fi, and cellular connections, as well as advanced setups such as bonds, bridges, VLANs, and tunnels.

You can supply the network configuration when you create an install image (so the device has connectivity from first boot) and you can update it later from the dashboard. When you push configuration from the platform, you choose how it combines with what is already on the device:

The device reports its observed network state back to the platform — active interfaces, IP addresses, and carrier information — which you can view on the device overview page.

Wired, Wi-Fi, and cellular

All three connection types are configured through the same network configuration document:

• Wired connections typically use DHCP by default and need no configuration to come up.
• Wi-Fi connections are configured with the network name and credentials.
• Cellular connections are configured for the modem; a device can also be associated with a SIM in the platform for inventory and activation tracking.

See the Netplan documentation for the exact YAML for each type.

Connection fallback

A field device often has more than one way to reach the network, and its configuration can be changed remotely. To keep a configuration mistake or a link outage from taking a device permanently offline, the OS has several layers of fallback — network configuration fallback, uplink (interface and cellular) failover, and proxy fallback. These are covered in detail on the Connection fallback page.

In this section

• Connection fallback — how the device stays reachable across bad config pushes, link outages, and proxy failures.
• Proxy configuration — route device traffic through an HTTP/HTTPS proxy.
• Connectivity & ports — what the device must be able to reach, and what it listens on.
• Time synchronization — set NTP servers and understand default time behavior.

4.1 -

Connection fallback

Devices are often deployed where connectivity is imperfect: a misapplied network change, a flaky uplink, or a proxy that goes down. SPEKTRA Edge OS has several fallback behaviors that keep a device reachable and recoverable. This page explains the three that matter most: network configuration fallback, uplink (interface and cellular) failover, and proxy fallback.

Network configuration fallback

When you push a new network configuration to a device, there is always a risk that the new configuration is wrong and takes the device offline — which would also prevent you from pushing a correction.

To guard against this, a device can fall back to a known-good network configuration that was established when the device was set up. If a platform-supplied configuration leaves the device unable to reach the platform, the device can revert to this baked-in configuration so it can be reached again.

You can control this behavior:

Uplink failover (interfaces and cellular)

A device can have more than one uplink — for example wired Ethernet plus cellular, or wired plus Wi-Fi. When multiple uplinks are configured, the device prefers the primary uplink and uses the others as backups, switching to a working uplink when the preferred one is unavailable.

A common, robust pattern is:

1. Wired Ethernet as the primary uplink (DHCP).
2. Wi-Fi or cellular as a backup that takes over when the wired link is down.

Cellular is especially useful as a last-resort uplink because it does not depend on local site infrastructure. Associate a SIM with the device during hardware registration, configure the cellular connection in your network YAML, and the device can fall back to it to stay manageable.

Proxy fallback

When a device is configured to reach the platform through a proxy, it still needs to stay reachable if that proxy becomes unavailable. The device evaluates the available paths to the platform and uses a working one, so a single failed proxy does not necessarily cut the device off from management.

This means you can introduce a proxy for normal operation without making it a single point of failure for device management, provided a viable path to the platform remains.

Putting it together

For a remote, hard-to-reach device, a resilient setup combines all three:

• Keep network configuration fallback enabled so a bad push self-corrects.
• Provide a backup uplink (cellular is ideal) so a single link failure does not isolate the device.
• If you use a proxy, ensure a viable path to the platform remains so proxy problems do not block management.

Next steps

• Review what must be reachable in Connectivity & ports.
• Configure a proxy in Proxy configuration.

4.2 -

Proxy configuration

If your devices reach the internet through a forward proxy, configure the proxy so that both the device’s connection to the SPEKTRA Edge platform and your workloads’ traffic are routed correctly.

What you can set

Proxy configuration consists of the standard proxy settings:

In addition, you can specify which network interfaces the device should use to reach the platform through the proxy, so control-plane traffic uses the intended path.

Where to set it

You can configure the proxy:

• at image creation, so devices use the proxy from first boot, or
• from the dashboard for a device that is already online.

The proxy applies both to the device’s own communication with the platform and to container workloads running on the device.

Fallback behavior

The device determines the best route to the platform and will fall back to a direct connection when the proxy is not usable, so a proxy outage does not necessarily take a device offline. If you require that all traffic traverse the proxy, ensure direct egress is blocked at the network level rather than relying on device configuration.

no_proxy recommendations

Add to no_proxy any destinations that must not go through the proxy, such as:

• on-site services the device talks to directly (local registries, local APIs)
• link-local and private ranges used on the device’s LAN

Next steps

• Review connectivity & ports to confirm what the device must reach through (or around) the proxy.

4.3 -

Connectivity & ports

This page lists what a device needs to reach on the network and what it accepts on its own interfaces, so you can plan firewall rules for the sites where your devices run.

Outbound connectivity (required)

A device reaches the SPEKTRA Edge platform over secure, outbound connections. Devices do not need any inbound connections from the platform — all communication is initiated by the device.

At minimum, allow outbound TCP 443 to the platform and outbound UDP 123 to your time sources. If you use a proxy, the device’s platform traffic egresses through it.

Inbound (on the device)

By default a device exposes only what is needed to administer it locally:

The device also responds to local network discovery (mDNS) so it can be found by name on the local segment; this can be turned off with the device discovery setting.

Any ports your workloads expose are determined by the workloads you deploy, not by the OS.

Remote access does not require inbound ports

Operator actions such as opening a remote shell, transferring files, or streaming logs are carried over the device’s existing outbound connection to the platform. You do not need to open inbound ports to use them. See Remote access.

Firewall planning checklist

• Allow outbound TCP 443 to the SPEKTRA Edge platform (directly or via proxy).
• Allow outbound UDP 123 to your NTP sources.
• Allow outbound UDP to your chosen STUN servers (or accept that external IP discovery is unavailable).
• Decide whether local TCP 22 (SSH) should be reachable on your LAN.
• Open any ports your workloads require, per workload.

4.4 -

Time synchronization

Accurate time is important for secure connections, certificate validation, log correlation, and device attestation. Devices keep their clocks synchronized over the network using NTP.

Default behavior

Out of the box, a device synchronizes against public time sources, so a device with internet access keeps accurate time without any configuration.

Setting custom NTP servers

If your environment requires specific time sources — for example, internal NTP servers on an isolated network — you can provide your own NTP configuration. You can set it:

• at image creation, so it applies from first boot, or
• by placing an NTP configuration on the device’s configuration storage.

When custom NTP settings are provided, they take effect early in the boot process so the device’s clock is correct before it contacts the platform.

Recommendations

• On networks without internet access, always configure reachable internal NTP servers; otherwise the device cannot correct its clock, which can cause secure connections and attestation to fail.
• Make sure outbound UDP 123 to your time sources is allowed — see Connectivity & ports.

5 -

Security

SPEKTRA Edge OS is built for devices that run unattended, often in physically exposed locations. This section explains the security controls available to you and how to configure them.

Security at a glance

Defaults worth knowing

• A device ships without a usable default password; you set the administrator password yourself. See User accounts.
• The device accepts only outbound connections to the platform; no inbound platform connection is required. See Connectivity & ports.
• Disk encryption is optional and is chosen when you create an image.

In this section

• Disk encryption — encrypt data at rest, with automatic unlock and a recovery passphrase.
• TPM & device attestation — hardware-backed identity and integrity verification.
• Secure Boot — verify the boot chain in firmware.
• SSH access — control shell access, keys, and source restrictions.
• User accounts — the administrator account and password recovery.
• USB device control — allow only approved USB devices.
• Remote access — operator access through the platform and what is recorded.

5.1 -

Disk encryption

Disk encryption protects the data at rest on a device, so that a lost or stolen device does not expose your configuration or workload data. This page explains what is encrypted, how a device unlocks itself, and how to recover access.

What is encrypted

When encryption is enabled, the two areas that hold your information are encrypted:

• the configuration area (device settings, identity, administrator password, hooks)
• the data area (container images, workload data, logs)

The boot and system-image areas are not encrypted; they contain only the operating system, which is public and identical across devices.

Enabling encryption

Encryption is chosen when you create an install image. You can also set an initial recovery passphrase at that time. Because enabling encryption affects how the disk is laid out, it is selected at image creation rather than toggled on a running device.

How a device unlocks itself

Encrypted devices unlock automatically at boot using the device’s hardware security module (TPM). The encryption keys are bound to the device’s hardware and to the integrity of its boot state, so the disk unlocks only on the same device, booted normally. There is no passphrase to type at the console during a normal boot, which is what allows encrypted devices to run unattended.

Because the keys are tied to the hardware, moving an encrypted disk to different hardware will not unlock it. This is the intended protection.

Recovery passphrase

In addition to automatic hardware unlock, a device can hold a backup recovery passphrase. This is a human-known passphrase you can use to unlock a device if automatic unlock is unavailable — for example after certain hardware changes.

Recommendations:

• Set a recovery passphrase (at least 12 characters) when you enable encryption.
• Store it securely, separately from the device.
• Treat it as a break-glass credential — it can unlock the encrypted areas.

Recovery scenarios

Related

• TPM & device attestation — the hardware module that backs automatic unlock.
• User accounts — administrator password and reset.

5.2 -

TPM & device attestation

Devices use a hardware security module — a TPM (Trusted Platform Module) — to establish a strong, hardware-rooted identity and to protect sensitive material. This page explains what the TPM is used for and how attestation works during provisioning.

What the TPM is used for

• Device identity. The TPM holds keys that uniquely and verifiably identify the device. These keys cannot be copied off the device.
• Attestation. During provisioning, the device proves its identity and reports its integrity to the platform before it receives credentials.
• Disk unlock. When disk encryption is enabled, the TPM stores the keys that unlock the encrypted areas, bound to the device’s boot state.

Attestation during provisioning

When a device onboards using zero-touch provisioning or a provisioning policy, it presents hardware-backed identity to the platform and responds to a challenge that proves the keys really live in this device’s TPM. Only after this succeeds does the device receive its credentials. This is what makes it safe to ship unconfigured hardware directly to a site: an attacker cannot impersonate a device without its TPM.

For attestation to succeed, the platform must trust the device’s TPM. This is established through the manufacturer’s certificates, which an administrator registers in the platform so that devices from a given manufacturer or product line can be verified.

Attestation configuration and status

You can configure attestation expectations for a device, and the device reports its measured integrity values back to the platform, where you can review them on the device. Use this to confirm that devices booted in the expected state.

Requirements

• The device must have a functioning TPM.
• The device’s clock must be reasonably accurate for the secure exchange to succeed — see Time synchronization.

Related

• Disk encryption — uses the TPM for automatic unlock.
• Secure Boot — complements attestation by verifying the boot chain.

5.3 -

Secure Boot

Secure Boot is a firmware feature that ensures a device only runs boot software that is cryptographically signed and trusted. SPEKTRA Edge OS supports Secure Boot so that the boot chain — from firmware through to the operating system — is verified before it runs.

Why use Secure Boot

Secure Boot protects against tampering with the boot path. Combined with disk encryption and device attestation, it raises the bar for an attacker with physical access: the device will refuse to boot modified or untrusted boot software.

What you need to do

On most generic x86 hardware, SPEKTRA Edge OS works with Secure Boot enabled using trust that is already present in the firmware, so you can simply leave Secure Boot enabled in the device’s firmware (UEFI) settings.

To enable or disable Secure Boot, enter the device’s firmware setup at boot and change the Secure Boot setting, as you would for any UEFI system. Refer to your hardware vendor’s documentation for how to reach firmware setup.

Locked-down firmware and certificate enrollment

Some hardware is locked down to trust only a specific set of signing certificates. In those environments you may need to enroll the SPEKTRA Edge signing certificate into the firmware’s trusted database so that the device will boot the OS.

If you operate such hardware, contact your SPEKTRA Edge representative for the signing certificate and enrollment guidance for your platform.

If a device will not boot with Secure Boot on

If a device fails to boot only when Secure Boot is enabled:

1. Confirm the firmware is up to date.
2. If the firmware requires explicitly trusted certificates, enroll the SPEKTRA Edge signing certificate (see above).
3. As a diagnostic step, temporarily disable Secure Boot to confirm it is the cause, then re-enable it once trust is established.

5.4 -

SSH access

A device runs an SSH server so you can reach its console for administration. You control whether SSH is enabled, how users authenticate, and where connections may originate. SSH settings are managed from the dashboard (or the API) and applied to the device automatically.

Enabling or disabling the SSH server

You can turn the SSH server off entirely for devices that should never accept direct shell access. With the server disabled, you can still administer the device through remote access over the platform connection.

Authentication

You can control how users authenticate:

Authorized keys

You can provide one or more authorized public keys. Each key entry supports the usual SSH key options, including:

• marking a key as a certificate authority, so SSH certificates it signs are accepted
• restricting a key to specific source addresses
• forcing a specific command
• applying restrictions and principals

Using a certificate authority is recommended for fleets: you can issue short-lived SSH certificates to operators instead of distributing individual keys to every device.

Restricting where connections come from

You can limit which source addresses may connect:

• an allow list of addresses/ranges permitted to connect
• a deny list of addresses/ranges that are blocked

This is the closest thing to a host firewall for SSH and is the recommended way to limit exposure when SSH must remain reachable on a LAN.

Brute-force protection

The device protects the SSH service against repeated failed login attempts by temporarily banning offending sources. You can tune this behavior through the device configuration, including:

• the ban duration applied to an offending source
• an ignore list of trusted sources that are never banned

Recommendations

• Prefer key or certificate authentication and disable passwords where possible.
• Use source restrictions to limit who can reach SSH.
• Keep an ignore list for your own management hosts so administrative tooling is not banned.

Related

• User accounts — the administrator account used for login.
• Remote access — administer devices without exposing SSH on the LAN.

5.5 -

User accounts

Each device has a local administrator account used for console and SSH access. This page explains how its password is set and stored, and how to recover access if the password is lost.

The administrator account

The administrator account (admin) has the privileges needed to operate the device locally. For security, devices ship without a usable default password — the administrator password is something you set yourself, so there is no well-known credential to exploit.

Setting the password

You can set the administrator password:

• at image creation, so it applies to every device built from that image, or
• when preparing installation media, on a per-device basis.

The password must be non-empty. It is stored only as a salted hash on the device’s configuration storage — the plaintext password is never written to the device. When the configuration area is encrypted, the stored hash is protected at rest as well.

Resetting a lost password

Because the password is stored on the device’s configuration storage rather than inside the read-only system image, it can be reset:

• by re-applying an administrator password to the device’s installation media, or
• by re-imaging the device if you also want to reset the rest of its configuration.

If the device is reachable through the platform, you can also continue to operate it via remote access while you arrange a local password reset.

Recommendations

• Use a strong, unique administrator password per fleet or per device.
• Enable disk encryption so the stored password hash and all configuration are protected at rest.
• Prefer SSH key or certificate authentication over passwords for routine access.

5.6 -

USB device control

USB device control lets you restrict which USB peripherals a device will accept, protecting against unauthorized devices being plugged into hardware in the field. It is configured from the dashboard (or the API).

How it works

When USB device control is enabled, the device accepts only USB peripherals that match your allow rules; everything else is rejected. When it is disabled, USB devices are accepted normally.

Allow rules

Each allow rule describes the USB devices it permits. You can match on:

Rules can match a specific value or one of a set of values, so you can, for example, allow a specific approved peripheral on any port, or allow only devices connected to a particular internal port.

Recommendations

• Enable USB device control on devices in physically exposed locations.
• Allow only the specific peripherals your deployment needs (for example, an approved cellular modem or sensor), and reject everything else.
• Account for peripherals that are part of the device itself when writing rules, so enabling control does not disable required internal devices.

5.7 -

Remote access

You can administer devices remotely through the SPEKTRA Edge platform without exposing any inbound ports on the device. Operator actions are carried over the device’s existing outbound connection to the platform.

What you can do remotely

Through the platform you can:

• open a remote shell on a device
• transfer files to and from a device
• stream system logs and container logs
• start, stop, and restart workloads
• reboot or shut down a device

These work from the dashboard and from the cuttle command-line tool.

No inbound ports required

Because remote access rides on the device’s outbound connection to the platform, you do not need to open inbound ports or expose the device to reach it. This is what lets you administer devices behind NAT or restrictive firewalls. See Connectivity & ports.

Relationship to SSH

SSH access governs direct connections to the device’s SSH server on the local network. Remote access through the platform is separate and works even when SSH is restricted to a LAN or disabled entirely — making “SSH disabled on the device, administer through the platform” a viable hardening posture.

Auditing

Operator access through the platform is associated with the authenticated user who initiated it, so administrative actions can be attributed. Combine remote access with your organization’s account controls to govern who may reach devices.

6 -

Operations

This section covers running devices day to day: upgrading the OS and rolling back, rebooting and recovering, collecting logs, checking device health, reading status indicators, running scripts at boot and shutdown, and deploying workloads.

In this section

• OS upgrades — move devices to a new OS version, and roll back.
• Reboot, shutdown & recovery — power actions and recovery options.
• Logging — forward system and container logs, and pull logs on demand.
• Health checks — define probes and read device conditions.
• Status & indicators — interpret device status, metrics, and LED states.
• Boot & shutdown hooks — run your own scripts at defined points in the device lifecycle.
• Running workloads — deploy containers to a device.

6.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.

6.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.

6.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.

6.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.

6.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.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.

6.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.

7 -

Reference

Quick lookups for configuring and operating SPEKTRA Edge OS.

In this section

• Configuration reference — the device settings you can manage, grouped by area, with links to where each is documented.
• Image settings — what you choose when creating an install image.
• Persistent paths — locations on the device you may place files in.
• Troubleshooting — playbooks for common problems.
• Glossary — terms used throughout this guide.

See also

• Connectivity & ports — the consolidated network requirements table.
• Devices API reference — the exact API fields behind these settings.

7.1 -

Configuration reference

This is an index of the device settings you can manage, grouped by area. Most are set from the dashboard or the API once a device is online; a few are chosen at image creation. For exact API field names and types, see the Devices API reference.

Runtime settings (dashboard / API)

These are reconciled to the device while it is online — change them at any time.

Image-creation settings

These are chosen when you create an install image; most can also be adjusted later through the runtime settings above.

On-device files

A few settings are provided as files on the device’s configuration storage — see Persistent paths.

7.2 -

Image settings

When you create an install image from the dashboard, you choose the device type, the OS version, and a set of defaults that are embedded in the image so a device is useful the moment it boots. This page summarizes those choices.

7.3 -

Persistent paths

Most configuration is applied through the dashboard or API. A few things, however, are provided as files on the device’s configuration storage — the persistent area that survives reboots and OS upgrades. This page lists the file-based settings you may need to place on a device.

File-based settings

Notes

• Files on configuration storage persist across reboots and OS upgrades; this is why they are the right place for durable, file-based settings.
• Do not place durable settings on the read-only system image — changes there do not survive a reboot. See how persistence works.
• When disk encryption is enabled, files on configuration storage are protected at rest.

7.4 -

Troubleshooting

Playbooks for the problems you are most likely to hit. Each lists the usual causes in the order worth checking.

A device will not come online

1. Connectivity. Confirm outbound TCP 443 to the platform is allowed (directly or via proxy). See Connectivity & ports.
2. Time. A badly wrong clock breaks secure connections and attestation. Ensure the device can reach an NTP source — see Time synchronization.
3. Network configuration. A recent network change may have broken connectivity; the device should fall back to its image network settings unless fallback is disabled. See connection fallback.
4. Onboarding. Confirm the device has valid provisioning credentials or a working onboarding method.

A network change broke connectivity

• If network configuration fallback is enabled, the device should revert to its image network settings after a failed change.
• If fallback is disabled, push a corrected configuration, or recover the device on-site.
• Configure a backup uplink (such as cellular) so a wired/Wi-Fi mistake does not isolate the device — see uplink fallback.

An encrypted device will not unlock

• After a hardware change (motherboard/TPM), automatic unlock no longer matches. Use the recovery passphrase.
• If the recovery passphrase is lost and automatic unlock is unavailable, the device must be re-imaged (encrypted data is not recoverable).

Locked out of SSH

• Your management host may have been banned after failed logins. Add it to the SSH ignore list to prevent this.
• Check the source allow/deny lists — your address may not be permitted.
• Administer the device through remote access while you fix SSH settings.

A USB device is rejected

• USB device control is enabled and the device does not match an allow rule. Add a rule for it, or confirm an existing rule matches its ID, port, or interface.

An OS upgrade did not complete

• Confirm the device can download the new version (connectivity and any proxy).
• A device that fails to start a new version can fall back to the retained previous version; you can also roll back explicitly.

The device is out of storage

• Container images, workload data, and logs share the data area. Check storage usage in device metrics.
• Lower logging severity if logs are consuming space.

A change I made on the device reverted

• The change likely modified the read-only system image. Apply it through configuration instead — see how persistence works and persistent paths.

7.5 -

Glossary

Terms used throughout the SPEKTRA Edge OS guide.

Attestation

The process by which a device proves its identity and reports its integrity to the platform using its TPM, before receiving credentials. See TPM & device attestation.

Configuration storage

The persistent area that holds device settings, identity, the administrator password, and hooks. Survives reboots and OS upgrades. See how persistence works.

Data area

The persistent area that holds container images, workload data, and logs. Uses most of the disk. See Storage.

Device type

The combination of hardware family and CPU architecture that identifies a platform and determines image compatibility. See supported platforms.

Disk encryption

Encryption of the configuration and data areas at rest, unlocked automatically by the TPM. See Disk encryption.

Hook

A user-provided script run at a defined lifecycle point (boot, after the agent starts, or shutdown). See Boot & shutdown hooks.

Onboarding / provisioning

How a device obtains an identity and joins a project — via zero-touch provisioning, a provisioning policy, or pre-registered hardware. See Device setup & provisioning.

Provisioning policy

A rule that lets devices self-register into a project from a template, either unattended or with manual approval. See onboarding methods.

Recovery passphrase

A human-known break-glass passphrase that can unlock an encrypted device when automatic unlock is unavailable. See Disk encryption.

Secure Boot

A firmware feature that allows only signed, trusted boot software to run. See Secure Boot.

System image

The read-only operating system a device boots from. Replaced as a unit during upgrades; not meant to be modified in place. See how persistence works.

TPM (Trusted Platform Module)

A hardware security module that provides device identity and protects keys, including the keys used for disk unlock. See TPM & device attestation.

Zero-touch provisioning

Onboarding in which unconfigured hardware automatically finds the platform, proves its identity, and receives credentials with no per-device setup. See onboarding methods.

8 -

Install the droplet agent (.deb package)

Most fleets run the purpose-built SPEKTRA Edge OS image. If instead you want to bring an existing Debian/Ubuntu Linux under management, you can install the droplet agent from a .deb package. The machine then joins your project and runs managed workloads, while you keep your own operating system.

This page walks you through the whole flow: install the package, create a provisioning policy and a service account, grant the service account a role, download its key, convert the key into a project_config.json, and place that file where the agent reads it.

Prerequisites

• Architecture: x86-64 (amd64) or ARM64 (arm64). These match the supported platforms for the OS image.
• Operating system: a Debian-based Linux (Debian or Ubuntu) with systemd and root/sudo access.
• Package dependency: wireguard (pulled in as a dependency of the package).
• Container runtime: Docker with Docker Compose, used by the default pod driver to run workloads.
• Platform access: the SPEKTRA Edge dashboard and an active project, with permission to manage provisioning policies, service accounts, service account keys, and role bindings.
• Local tools: jq (used to build project_config.json).

Default-enabled functions

The packaged systemd unit starts the agent with the pod driver and with OS management disabled:

droplet run --driver compose --disable-os-management \
  --device-service-account-file /etc/droplet/device_config.json \
  --project-service-account-file /etc/droplet/project_config.json \
  --use-journald-compatible-log

As a result, on a .deb install:

If you want to enable additional capabilities, edit the ExecStart line in /lib/systemd/system/droplet.service (each capability has its own --disable-* flag) and reload with sudo systemctl daemon-reload.

Not available with the package install

The .deb agent runs on your operating system, so the platform features that are properties of SPEKTRA Edge OS itself are not available. You remain responsible for the host OS. In particular, the following are not supported:

What you do get is device onboarding, remote workload/pod management, and telemetry — see Default-enabled functions.

Install the package

Copy the .deb matching your architecture onto the host and install it:

sudo dpkg -i droplet_<version>_<arch>.deb
# resolve dependencies (e.g. wireguard) if dpkg reports any
sudo apt-get install -f

The package:

• installs the agent binary at /usr/bin/droplet,
• installs the service unit at /lib/systemd/system/droplet.service,
• creates the working directory /var/lib/droplet,
• enables and starts the droplet service automatically.

At this point the service is running but has no identity yet. It will keep retrying until you supply project_config.json, which you provide in the next section.

Create the agent’s identity (project_config.json)

The agent onboards using a project-scoped project_config.json. There are two ways to obtain it — pick one:

• Reuse from an existing device (fastest). If you already have a device that onboards against the same project and provisioning policy, its project_config.json is a shared credential you can copy as-is. Grab it from that device — /etc/droplet/project_config.json on a package install, or /isodevice/config/project_config.json on SPEKTRA Edge OS — and skip straight to Install the identity file. See Reuse across devices for why this is safe.
• Create from scratch. If this is a new project or you want a dedicated credential, follow the numbered steps below to create a provisioning policy, a service account with the right role, and a key, then convert it.

The steps below cover the create-from-scratch path.

Step 1 — Create a provisioning policy

A provisioning policy lets a device self-register into your project. Create one in the dashboard and choose a mode:

The policy also defines the role bound to each newly created device identity (default: services/devices.edgelq.com/roles/v1-device-agent). See provisioning concepts for background.

Step 2 — Create a service account

In the dashboard, open your project and create a Service Account (for example fleet-provisioner). This is the shared, project-scoped identity that devices will present in order to self-provision.

Step 3 — Assign the provisioning role and attach it to the policy

For the service account to be allowed to provision devices, it needs the Device provisioner role:

services/devices.edgelq.com/roles/v1-device-provisioner

This role grants the provisionDeviceViaPolicy and requestProvisioningApproval permissions (scoped by project, region, service account, and provisioning policy).

1. Bind the Device provisioner role to the service account from Step 3.
2. Associate the service account with the provisioning policy from Step 2, so devices using this account are matched to that policy.

Step 4 — Create and download a service account key

Open the service account → Service Account Keys → Create. On creation the dashboard downloads a JSON key file (shown only once). Save it as service-account-key.json. It looks like:

{
  "type": "service_account_key",
  "client_email": "fleet-provisioner@<project>.<region>.serviceaccounts.iam.edgelq.com",
  "private_key_id": "projects/.../serviceAccountKeys/<key>",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
}

Step 5 — Convert the key to project_config.json

The agent expects the key wrapped in a config with a droplet service set. Build it from the downloaded key, setting defaultDomain to the controller endpoint your device connects to (for example apis.edgelq.com, or your dev/staging domain):

jq --arg domain "apis.edgelq.com" '{
  accounts: [ { serviceAccount: (. + {type: "service_account"}) } ],
  activeAccountName: .client_email,
  serviceSets: [ { name: "droplet", defaultDomain: $domain } ],
  activeServiceSetName: "droplet"
}' service-account-key.json > project_config.json

The result:

{
  "accounts": [
    {
      "serviceAccount": {
        "type": "service_account",
        "client_email": "fleet-provisioner@<project>.<region>.serviceaccounts.iam.edgelq.com",
        "private_key_id": "projects/.../serviceAccountKeys/<key>",
        "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
      }
    }
  ],
  "activeAccountName": "fleet-provisioner@<project>.<region>.serviceaccounts.iam.edgelq.com",
  "serviceSets": [ { "name": "droplet", "defaultDomain": "apis.edgelq.com" } ],
  "activeServiceSetName": "droplet"
}

Notes:

• activeAccountName must equal the client_email.
• Keep private_key on one line with its \n escapes intact (valid JSON).
• defaultDomain is the controller endpoint the agent connects to — not the IAM host inside the email.

Install the identity file

Whether you reused an existing project_config.json or created one above, install it where the packaged service reads it, and lock down its permissions (it contains a private key):

sudo install -o root -g root -m 600 project_config.json /etc/droplet/project_config.json
sudo systemctl restart droplet

Reuse across devices

project_config.json is a shared, project-scoped credential — it is not tied to any single machine. That means:

• You can reuse an existing project_config.json taken from another device that already onboards against the same project and policy.
• You can copy the same file to many devices. Each device presents this shared identity only to self-provision; on success it receives its own, device-scoped identity (/etc/droplet/device_config.json) and uses that from then on.

This is why a single install image or a single copied config can serve an entire fleet, with no per-device credential preparation.

Verify

1. Watch the agent logs:

   journalctl -u droplet -f
   

   The agent should load the project config and attempt self-provisioning.

2. In the dashboard, under your project:

   • Unattended: a new Device appears automatically.
   • Manual approval: a pending provisioning request appears — approve it.

3. Once provisioned, the device shows as Online and reports its OS version, hardware, and network details.

If the device does not come online, check the connectivity requirements and the troubleshooting playbooks.