Getting Started with Rugix

This quickstart guide continues the Rugix quickstart guide and provides step-by-step instructions for integrating Nexigon into your Rugix project. It takes you through the steps required to onboard a device and connect to it through Nexigon's remote access functionality. End-to-end this guide should take less than 15 minutes to complete. So, let's get started.

info

To follow this guide, you need access to a Nexigon instance. As part of our SaaS offering, Nexigon Cloud, we offer free accounts for up to 10 devices for 6 months. Creating an account there only takes a few minutes, no credit card required. 👉 Click here to create a free account now. 👈

Please return back to this guide after creating your account.

Creating an Organization

Within Nexigon, access rights are scoped to organizations at the top level. To on-board a device, you first need to create an organization (if you haven't done so already). After signing up for an account in Nexigon Cloud, you will be greeted by a dialog to create an organization.

As part of the organization creation, you are asked for S3 credentials. Those are required for the software artifact management functionality. You can use any S3-compatible provider or just skip this step for now.

Deployment Tokens

Devices can be organized into projects, this is useful, e.g., to strictly isolate production and testing environments. When creating an organization through Nexigon Cloud, a “Default Project” will be created for you. Initially, the Default Project won't have any devices connected to it and you will be greeted with an onboarding dialog when opening the Devices view through the sidebar on the left:

With Nexigon, security is non-negotiable and a foundational design principle. When you connect a device, it authenticates using three independent factors to ensure that only authorized devices can join your infrastructure:

1. Device Certificate — unique cryptographic identity of a device used for mutual TLS authentication.
2. Deployment Token — identifies the target project and may constrain what a device is allowed to do.
3. Device Fingerprint — hardware-specific fingerprint computed from hardware characteristics.

Before you can connect a device, you need to generate a deployment token. You can do so by just clicking on the “Create” button. If you want, you can also give the token a proper name.

tip

Note that you have to copy the token after creation, as you will not be able to access it through Nexigon afterwards. In fact, Nexigon does not store the token but only its hash in order to minimize the attack surface, e.g., in case a database dump is compromised. In general, Nexigon will never store any authentication information in plain text, including deployment tokens.

With your deployment token, you will now be able to integrate Nexigon into your Rugix project. Let's go!

Integrating Nexigon

To integrate Nexigon into your Rugix project, we provide a ready-made Rugix repository for Nexigon. As a first step, you need to add this repository to your Rugix project. To this end, add the following to your rugix-bakery.toml file:

rugix-bakery.toml

[repositories]
nexigon = { git = "https://github.com/nexigon/nexigon-rugix.git", branch = "v0" }

To connect a device, the device needs to run Nexigon Agent, the open-source device agent of Nexigon available for Linux, macOS, and Windows. To install and configure the agent, you need to add the following recipes to your Rugix Bakery layers:

• nexigon/nexigon-agent: Installs Nexigon Agent into the system.
• nexigon/nexigon-agent-config: Configures Nexigon Agent.

For instance, your customized layer might now look like this:

layers/customized.toml

#:schema https://raw.githubusercontent.com/silitics/rugix/refs/tags/v0.8.0/schemas/rugix-bakery-layer.schema.json

parent = "core/debian-bookworm"

recipes = [
    # Set a static hostname.
    "core/set-hostname",
    # Persist `/root`.
    "core/persist-root-home",
    # Setup and enable SSH.
    "core/ssh",
    # Setup the network.
    "rugix-extra/debian-setup-network",
    # Setup the time synchronization.
    "rugix-extra/debian-setup-timesyncd",
    # Enable discovery of the system in the local network.
    "rugix-extra/avahi",
    # Setup Nexigon Agent.
    "nexigon/nexigon-agent",
    # Configure Nexigon Agent.
    "nexigon/nexigon-agent-config",
    # Install a static web site.
    "hello-world",
]

The nexigon-agent-config recipe takes the configuration from a local .env file containing the instance URL and the deployment token of the project you want to connect your devices to. Here is an example .env file:

.env

# Nexigon Configuration
NEXIGON_HUB_URL="https://eu.nexigon.cloud"
NEXIGON_TOKEN="deployment_HRq4Xfdjbo6sZ6bYJJm2SAqfgvFAnXcEdSytpwq8bTTMaXZyqZBu9egnmLQ8he4td3"

note

While the deployment token is not strictly considered secret, it is nevertheless recommended to not commit it into version control. Hence, the recipe loads it from the .env file which should be added to the .gitignore file.

With the recipes added and the .env file in place, you can now build an image and deploy it to a device, or start a VM.

If everything has been successful, the agent should start up when you boot the device or VM and will then try to connect to Nexigon. On the Devices page of the project within Nexigon's UI, you should now see a new, unnamed device:

note

In case the device does not show up, check the agent's log output with journalctl -u nexigon-agent.

If you click on View →, you can inspect the device. Here, you also find an overview over the device's certificates. By default, deployment tokens are configured to allow for automatic provisioning where the first certificate presented by a new device is accepted. Of course, you can also disable this feature and manage device certificates explicitly, e.g., backed by your own CA.

tip

For most use cases, the self-signed certificates generated by Nexigon Agent should be fine and there is no need for a dedicated CA. Nexigon takes care of checking the certificates via their fingerprint.

Establishing a Remote Connection

In case the device runs a local webserver, you can establish a remote connection directly through the Nexigon UI, via the “Generate URL” menu item. The Generate URL dialog allows you to generate a URL with an access token to access an HTTP server running on a specific port.

Alternatively, you can use the Nexigon CLI to establish a remote connection and forward arbitrary ports of the device to your local machine. On macOS and Linux, you can download Nexigon CLI with the following command:

curl -sfSL https://install.nexigon.dev/download-cli.sh | sh

This will download the CLI to the current working directory. You can then run it with:

./nexigon-cli

To use the CLI and connect to the device, you need to configure the CLI with the URL of the Nexigon instance and a user access token. To create an access token for your user, open the user's security settings by clicking on the user icon in the bottom left, then go to Settings and then Security. By clicking on New Token, you can create a new user token. As with the deployment token, you need to copy the token after creation, as you will not be able to access it through Nexigon afterwards.

To configure the CLI, run the following command, and enter the instance URL and your user token:

./nexigon-cli configure

The command will create a configuration file ~/.nexigon/cli.toml.

Afterwards, you will be able to establish a remote connection to the device with:

nexigon-cli forward <device id> <local port>:<remote port>

Here, <device id> is the ID of the device you want to connect to. The device ID starts with d_ and can be found in the Nexigon UI. For instance, to forward port 22 of the device to port 2222 on your local machine, run:

nexigon-cli forward <device id> 22:2222

You can then use the forwarded port to connect to the device via SSH:

ssh -p 2222 root@localhost

Conclusion

Congratulations on completing the Nexigon quickstart guide for Rugix!

You have successfully integrated Nexigon into your Rugix Project, onboarded a device, and established a remote connection to it. From here, you can begin exploring the full range of Nexigon’s capabilities. As always, if you have questions or feedback, we’d love to hear from you, just get in touch.

tip

To enable OTA updates through Nexigon, check out the Nexigon template for Rugix Bakery and adapt the scripts and integration with nexigon-rugix-ota as necessary.