Getting Started 🚀

This quickstart guide will take 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 working Nexigon instance. For evaluation and demonstration purposes, we provide a free instance at demo.nexigon.dev. Creating an account there only takes a few minutes, no credit card required.

👉 Click here to create a free account now. 👈

After setting up Nexigon or creating an account on our demo instance, you can log into Nexigon's web UI. Generally, all functionality accessible through the UI is also exposed via Nexigon's HTTP API, so you can automate all aspects of Nexigon.

Projects and Deployment Tokens

Within Nexigon devices are organized into projects. To connect a device, the first step is to create a new project. To this end, within the Projects tab of Nexigon's UI, click on Create Project, give the project a name, and confirm the creation.

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. To do this:

1. Open your newly created project (should open automatically after creation).
2. Navigate to the Tokens page using the menu on the left.
3. Click on New Token within the Deployment Tokens section.
4. Give the token a descriptive name and confirm the creation.
5. Copy the token and save it somewhere safe, you will need it later.

note

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.

With your deployment token, you will now be able to onboard a device. Let's go!

Onboarding a Device

To onboard a device, you need to install and configure Nexigon Agent. Nexigon Agent is Nexigon's open-source device agent available for Linux, macOS, and Windows.¹ For the purposes of this quickstart guide, we will assume that your device runs Linux. For other operating systems, please follow the platform-specific instructions found in the documentation.

To download and install Nexigon Agent on Linux in an ad-hoc way, run the command:

curl -sfSL https://install.nexigon.dev/install-agent.sh | TOKEN="..." sh

Here, TOKEN needs to be set to the deployment token of the project you want to connect the device to. The URL of the Nexigon instance can be changed by setting the HUB_URL environment variable. By default, the demo instance is used.

Unless ran as root, the installation script will ask you for your password. It will install Nexigon Agent to /usr/bin and further install a Systemd service. For production, we recommend using Yocto, Rugix, or a similar build system for embedded Linux.

If the installation has been successful, the installer should have started the agent and the agent will try to connect to Nexigon. On the Devices page of the project within Nexigon's UI, you should now see a new, unnamed device:

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.

Establishing a Remote Connection

In case the device runs a local webserver, you can establish a remote connection directly through the Nexigon UI, by clicking on View → and then on HTTP Proxy. This requires the webserver to run on the default port 80. The built-in HTTP reverse proxy also allows accessing HTTP servers on other ports, however, this functionality is not yet available directly in the UI.

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 top right corner, 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!

You have successfully 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.

Footnotes

1. Built-in functionality does vary across the different platforms. ↩