On-board edge devices

This page explains how to prepare an edge device, connect it to MK.IO, register it to a project, and remove it when needed.

Prerequisites

• The device is updated to the latest software version. See the product manual.
• You can access the device's local web UI at http://<edge-device-ip>.
• The device can reach api.mk.io on HTTPS port 443. See Connect the device to MK.IO and confirm the Connected field is green.
• Connection to the public internet can be achieved using a proxy, see Configure an HTTP proxy.

Add the device to MK.IO

The on-boarding process has two steps:

1. From the device's local web UI, connect the device to MK.IO. When successful, the UI displays a short code.
2. Use the short code to register the device, either via the MK.IO UI or via the MK.IO API.

Once registered, the device is available for monitoring and control through MK.IO.

Configure an HTTP proxy

1. Open the device's local web UI: http://<edge-device-ip>
2. Go to Appliance > Fleet.
3. Click next to the Connected field.
4. Enter the Proxy IP Address, Port, Username, and Password. Only printable ASCII characters are allowed in the Password field. Space, colon, and backslash are not permitted.
5. Click Apply.

Connect the device to MK.IO from the device UI

1. Open the device's local web UI: http://<edge-device-ip>
2. Go to Appliance > Fleet. After a few seconds, additional information appears.
3. Confirm the Connected field shows Yes. This confirms the device can reach MK.IO.
4. Note that the Registered field shows No until you complete registration.
5. Copy the short code (eight random letters and numbers) from this page.

Add the device using the MK.IO UI

1. In a separate browser tab, log in to MK.IO. If you do not have an account, see Sign up to MK.IO.
2. Open the project you want to add the device to and go to the Devices page.
3. Click Add device, then enter the short code, a display name, and the site.
4. Click Add. The device appears in the list of edge devices.

Add the device using the MK.IO API

You can register the device via API using the short code in the spec.shortCode field. Alternatively, use the longer-lived device ID shown in the device's web UI in the spec.locationId field:

PUT https://api.mk.io/api/v1/projects/project_name/fleet/devices/device1

{
  "metadata": {
    "displayName": "Device 1"
  },
  "spec": {
    "siteName": "world",
    "locationId": "a7dafdba-4923-4317-aad1-dc76284b85b5"
  }
}

Verify on-boarding

Once the device is registered, go back to Appliance > Fleet in the device's local web UI. The Registered field shows Yes and displays the device's name.

You can now view device information and access the remote UI.

Remove a device

Remove using the MK.IO API

To remove a device, send a DELETE request:

DELETE https://api.mk.io/api/v1/projects/project_name/fleet/devices/device1

Resolve removal warnings

The API (and UI) may prompt you with a warning if either of the following is true:

• The device does not have an up-to-date usage report.
• The last usage report shows services were still running on the device.

To resolve this:

1. Confirm the device is powered on and can connect to MK.IO. Check the Connected status under Appliance > Fleet.
2. Stop all services on the device. Use the remote UI if needed.
3. Wait for the usage report to update. This can take 10–20 minutes.
4. Retry the DELETE request.

Force delete an unreachable device

If the device cannot be accessed due to hardware failure, force the deletion by adding query parameters to the request:

DELETE https://api.mk.io/api/v1/projects/project_name/fleet/devices/device1?force=true&reason=<reason>&notes=<notes>