Skip to main content

Linux

Atym runs on Linux-based systems as a lightweight process that can run in the background and connects your device to the Atym Hub — no flashing or board-specific setup required.

Atym currently provides Linux builds for x86_64 and aarch64 architectures, supporting devices from Intel/AMD-based systems to development boards like the Raspberry Pi 4/5.

Prerequisites​

Before setting up your device with Atym, ensure you have the following:

Hardware​

  • A Linux target device (x86_64 or aarch64)
  • An active internet connection

Software​

  • Atym CLI installed on your development machine (you'll use it to register the device)

Prepare Your Device​

Simply connect your Linux target device to an active internet connection. No additional board-level setup is required.

Add Device to the Atym Hub​

First, create a digital identity for your Linux device in the Atym Hub using the Atym CLI on your development computer. Later in this guide, you’ll apply those credentials directly on the Linux device itself to register it with the Atym Hub.

Run the following command, replacing the values with your own (see the add device CLI reference for all available options):

atymctl device add --deviceName "testDevice" --description "My test device" --serialNumber "1234567890"

If successful, you’ll receive a response containing your deviceUUID, pskSecret, and tenantUUID. For example:

{
  "deviceUUID": "67c1c350-cc1c-482d-bde9-875688ff9b23",
  "pskSecret": "IEAaeWHKhYs4fAScF5ApQ0C9eGcXu123",
  "tenantUUID": "2C9D9E73-702E-49DF-8181-F7B56849B864"
}

Copy all three values to a secure location — you’ll need them when configuring your Linux device.

Download and Install Atym​

The Atym Linux runtime is distributed as a tar.gz archive containing a statically linked binary. Archives are available for x86_64 and aarch64 architectures.

  1. On your Linux device, download the correct archive for your architecture:
wget https://atympublicshare.blob.core.windows.net/runtime/linux/latest/atym-runtime-ubuntu-x86_64.tar.gz
Alternative

You can also download the archive on your development machine and transfer it to your Linux device using scp.

  1. Extract the archive:
tar -xzf atym-runtime-ubuntu-x86_64.tar.gz

This extracts the following into the current directory:

  • atymd - The Atym runtime binary
  • sbom/ - Directory containing Software Bill of Materials files (SPDX format)

Register Device with the Atym Hub​

Now configure your Linux device with the credentials generated earlier. The Linux runtime reads its configuration from environment variables — there is no on-device atym shell to configure.

Device Console Required

The following steps must be performed on your Linux target device, NOT your development machine.

  1. Set the device identity using your deviceUUID and tenantID:
export ATYM_PSK_ID="deviceUUID@tenantID"
  1. Set the device's pre-shared key:
export ATYM_PSK_KEY="pskSecret"
  1. (Optional) Override the default Atym Hub endpoint. If unset, the runtime connects to the default production Hub.
export ATYM_BASE_URL="coaps://coapgw.prod.atym.io:5684"
  1. Verify the variables are set:
env | grep ATYM_

Example output:

ATYM_PSK_ID=a612baee-dd15-42cc-a0dc-a0783c186bb5@a60dbceb-270e-4b14-a93c-60809b34c123
ATYM_PSK_KEY=ct6P/zFOHQbvrLyRFrnh22XnXQ1H8+at
info

export sets the variables for the current shell session only. To persist them across reboots, add the export lines to your shell's startup file (e.g., ~/.bashrc) or define them in a systemd service unit if you plan to run the runtime as a service.

  1. Start the Atym runtime:
./atymd

If your device successfully connects to the Atym Hub, you'll see the following message in the terminal output:

Client connected successfully

Next Steps​

Congratulations! Your Linux device is now configured and securely connected to the Atym Hub. You can begin deploying and running containerized applications just like on a development board.

Continue with the Build and Deploy Containers guide to create, build, and deploy your first containerized application.