Air Link

Air Link is a standalone service to manage remote access to an edge device and to install user apps.

Prerequisites

Python Environment

The edge device needs to run a Linux-based OS. We recommend uv, which brings its own Python and keeps Air Link isolated from the rest of the system:

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.profile # or open a new login shell

Setup

1. Install the Air Link app on an edge device

Install Air Link as a uv tool. To run the app automatically after a reboot, you can install it as a system service using its install command.

uv tool install --python 3.14 air-link
air-link install <on air token>

The service unit grants Air Link the CAP_NET_RAW capability, which it needs to ping a public host once per second to keep a history of the network state. The capability applies to the service process only, so it survives Python upgrades and does not affect other apps on the device.

Note

To update Air Link later on, run uv tool upgrade air-link. Re-run air-link install afterwards if the service unit shipped with the new version has changed.

After that, Air Link is accessible via the IP address of the edge device on default port 4230 (http://localhost:4230). If you have provided an On Air token, the app is also accessible via NiceGUI On Air (see below).

Note

To make the app accessible over an SSH tunnel, you can log into the edge device with the following command:

ssh -L 8888:localhost:4230 <target device>

The app will then be reachable at localhost:8888 on your developer machine.

Tip

To display the logs of the Air Link service, use the following command:

journalctl -u air-link -f

The -f flag will follow the logs in real-time.

2. Access via NiceGUI On Air

To make the Air Link app accessible via NiceGUI On Air, follow these three steps:

1. Register a new device with a fixed region at https://on-air.nicegui.io.
2. Run air-link set-token <on air token> to save the token to NiceGUI's general storage. Alternatively, you can enter the token in the top right corner of the Air Link web interface.
3. Restart the Air Link service using systemctl restart air-link.service or the button on the top right corner of the Air Link web interface.

Air Link will be reachable through the URL provided by NiceGUI On Air, for example https://europe.on-air.io/zauberzeug/demo-air-link. We strongly suggest to set a fixed region for the device at https://on-air.nicegui.io to keep the URL stable.

3. Manage SSH keys (optional)

To allow SSH access without a password, you can add SSH keys to the edge device using the Air Link web interface. Use the key icon in the top right corner to open the SSH key management.

Usage

Install User Apps

You can install user apps via the Air Link web interface. The web interface lists all available packages and provides a button to upload additional ZIP files. The install button runs the install.sh script from the ZIP file and outputs the process in the web interface.

SSH Login via NiceGUI On Air

Establish an SSH connection to the machine where Air Link is running via proxy jump over the On Air server:

ssh -J <your_organization>/<your_device_name>@<your_region>.on-air.io <username_on_device>@localhost

Explanation: The combination of organization and device name before the @<region>.on-air.io tells the On Air server where to route the SSH login. The last bit tells SSH with which user you want to log into the edge device (which is localhost after Air Link received the tunneled data from the On Air server).

Tip

You can also put the proxy jump into your ~/.ssh/config to establish a connection with the bash command ssh my-device:

Host my-device
    User <your_username>
    HostName localhost
    ProxyJump <your_organization>/<your_device_name>@<your_region>.on-air.io

It may also be beneficial to add the following configuration to the host entry:

    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
    ServerAliveInterval 30
    ForwardAgent yes
    SetEnv GIT_AUTHOR_NAME="Your Name" EMAIL="your.email@example.com"

Development

Design Decisions

• Assume an edge device with a Linux-based OS and Python >=3.10.
• Run side-by-side with user apps, because deploying/breaking a user app should not affect remote access.
• Provide SSH access to the edge device through the websocket tunnel from NiceGUI On Air.

Setting Up the Environment

We use uv to manage the development environment:

uv sync

Testing Locally

1. Start On Air server with ./main.py.
2. Modify Air Link main.py to point to the local On Air server: import nicegui.air and nicegui.air.RELAY_HOST = 'http://localhost'.
3. Start Air Link locally with uv run ./main.py run.
4. Establish an SSH connection to your local machine via proxy jump over the On Air server: ssh -J zauberzeug/rodja@localhost:2222 rodja@localhost.

Note

Outside the systemd service Air Link has no CAP_NET_RAW capability. It then logs a warning once and records the network as down, unless the system allows unprivileged ICMP sockets, e.g. via sudo sysctl -w net.ipv4.ping_group_range="0 $(id -g)" on Linux.

Running Tests

uv run pytest
uv run mypy air_link

Both also run in CI for every pull request.

Formatting

We use pre-commit to make sure the coding style is enforced. You first need to install the corresponding git hooks by running the following command:

uv run pre-commit install

After that you can make sure your code satisfies the coding style by running the following command:

uv run pre-commit run --all-files

These checks will also run automatically before every commit.

Deployment

To deploy a new version of Air Link, add a new tag with the format vX.Y.Z and push it to the repository. The CI pipeline will then build the new version, upload it to PyPI, and create a new draft release on GitHub.