Skip to content

Bootstrapping a device

Legacy agent version instructions (qbee-agent version < 2023.XX)

Instructions for the legacy version of qbee-agent can be found here

Default bootstrapping

Bootstrapping is the process of securely pairing the device with the server. Here the initial trust between the device and the server is established through the creation and exchange of individual keys. A typical bootstrap command will look like this and is given as an output from the qbee agent installation. How to obtain the bootstrap key is explained in the next paragraph. This will be executed on the agent. If you are using a proxy or are interested in more options please go to the bottom of this page.

    sudo qbee-agent bootstrap -k <bootstrap_key>

Check the path for your platform

Depending on your platform this command might have a different path or command. Please refer to the output of your agent install.

Get your bootstrap key from here

The bootstrap key can be found in the menu below the username.


Executing the bootstrap command will start the communication with the server. You will see a feedback on the agent command line how the bootstrap process is commencing. If successful your device should appear under the "All devices" section in the tree under "Devices".

Bootstrap key options

Bootstrap key options

The bootstrap key menu in qbee allows for a lot of flexibility. You can do the following:

  • Automatically accept devices
    Devices will be accepted into the system with no manual interaction (default)

  • Define the group devices will be inserted in:
    It is possible to define a specific group assignment for a specific key. All devices bootstrapping with that key will be assigned to the specific group.

  • Add multiple keys:
    It is possible to define multiple bootstrap keys. For example if different producers create the original system image.

  • Revoke bootstrap keys
    It is possible to revoke any bootstrap key. Devices that have bootstrapped already are in no way impacted by this. New devices that bootstrap with this key will be rejected.

This is how the bootstrap key menu looks like when you edit it:


The group selector allows you to automatically add devices to specific groups immediately inheriting that configuration.

There is also a way to manually accept devices. Just select auto-accept "No". Then you need to manually accept each device individually.

Manually accepting devices

Depending on your settings you can enable "auto accept" yes or no for a certain bootstrap key. "Auto accept" is the default setting. If "no" is selected you need to manually accept the device.

If you manually accept devices please check if the IP of the device and the request time is correct and then approve the device in the qbee UI under Devices -> Pending devices.


When the device is approved it takes a while before it is visible in the tree. Eventually it will appear in the tree or under a group called "unassigned devices" if that was selected for the bootstrap key. This is important as there is no configuration associated with the "unassigned group". First if you move the device into a group that has configuration or if you create a group and then define configuration this device is in a defined state. Do not forget to save the new tree.

Make sure your device is not in unassigned devices

Any new device needs to be accepted in the "Pending devices" tab. When that is done it will appear under "unassigned devices" in the tree. Try reload the page if it does not appear. Only when you move it form "unassigned" into the main tree or any of your groups it will receive the valid configuration for that group and start working. Devices in the unassigned group are not working yet.


Command line options for the bootstrap command

The qbee agent can be called with more options. The complete set of settings can be seen here:

$ sudo qbee-agent bootstrap -h
Usage: qbee-agent [global options] <command> [options] [<command> [options] ...]

  -k, --bootstrap-key BOOTSTRAP_KEY    Set the bootstrap key found in the user profile.  [required]
      --disable-remote-access          Disable remote access.                            [optional]
      --device-name DEVICE_NAME        Custom device name to use.                        [optional]
      --proxy-host PROXY_HOST          HTTP proxy host to use.                           [optional]
      --proxy-port PROXY_PORT          HTTP proxy port to use.                           [optional]
      --proxy-user PROXY_USER          HTTP proxy username.                              [optional]
      --proxy-password PROXY_PASSWORD  HTTP proxy password.                              [optional]

Proxy settings available

These settings allow to configure qbee connections through a proxy. Please note that we currently only support http proxy connections. But since the communication of the qbee agent is highly encrypted this is no security concern.


Your device needs to be able to resolve DNS and the firewall needs to allow to initiate output traffic. If problems occur under bootstrapping please try iptables -F OUTPUT. Then in qbee you go into configure->firewall and enable that for the receptive devices. Even if the firewall is configured to "drop" all it enables qbee to get through.