Install a node in Vagrant

You can create virtual Great Bear nodes in VirtualBox using Vagrant. To prepare a virtual machine to use as a Great Bear node using Vagrant, complete the following steps.


  • Make sure that your system supports Vagrant and the associated virtualization provider (in this case, VirtualBox). At the time of writing the systems we have validated are Apple Mac x86 and Windows x86.
  • You have downloaded and installed VirtualBox.
  • You have downloaded and installed Vagrant.
  • The node must be able to access the Internet on TCP port 443.

Create and bootstrap a new VM

  1. Create a new directory and create a file called Vagrantfile into the directory with the following contents:

    # -*- mode: ruby -*-
    # vi: set ft=ruby :
    Vagrant.configure("2") do |config|
        config.vm.define "node-0" do |leader|
 = "ubuntu/jammy64"
          leader.vm.hostname = "node-0"
 "private_network", ip: ""
          # Uncomment the next line for enabling VNC server with the EDD application on VM node-0
 "forwarded_port", guest: 5900, host: 5901
        config.vm.define "node-1" do |worker1|
 = "ubuntu/jammy64"
          worker1.vm.hostname = "node-1"
 "private_network", ip: ""
          # Uncomment the next line for enabling VNC server with the EDD application on VM node-1
 "forwarded_port", guest: 5900, host: 5902
        config.vm.define "node-2" do |worker2|
 = "ubuntu/jammy64"
          worker2.vm.hostname = "node-2"
 "private_network", ip: ""
          # Uncomment the next line for enabling VNC server with the EDD application on VM node-2
 "forwarded_port", guest: 5900, host: 5903
        config.vm.provider "virtualbox" do |vb|
           vb.memory = "2048"
        config.vm.provision "shell", inline: <<-SHELL
           apt-get update 1>/dev/null

The Vagrantfile defines three VMs, named node-0, node-1 and node-2.

  1. Start a virtual machine by running vagrant up [machine name] - if you omit machine name, vagrant will bring up all three VMs

    Note: If you receive an NS_ERROR_FAILURE error when starting the VM, check the security permissions of VirtualBox.

Bootstrap the node


  1. Select the node you want to bootstrap. For example, for node-0 type vagrant ssh node-0

  2. Set the HARDWARE_ID environmental variable. This value will be used to register the node in the dashboard. For example: export HARDWARE_ID="xx:xx:xx:xx:xx:xx"

    Note: The HARDWARE_ID must be:

    • Unique within Great Bear, as this ID also identifies the node on the dashboard.
    • Between 8 and 128 characters long.
    • Include only ASCII letters (A-Za-z), numbers (0-9), and the :-_ characters.

    Using the MAC address, the serial number of the CPU, or a similar Universally Unique Identifier (UUID) is a convenient way to make sure the ID has not already been used within Great Bear.

  3. Run the following command to bootstrap the node:

    curl | \
    TOKEN=<access-token> DEVICE_KEY=<device-key> sh

    Note: You can bootstrap the node with an agent showing more verbose logs by adding the LOG_LEVEL=DEBUG option.

  4. That’s it! Next you can Start using your node.


In case you encounter problems, see our Troubleshooting guide.

Stop or delete the VM

If you stop the VM, the Great Bear dashboard will show that the node is offline. You can start the node again to bring it back online later if needed.

If you delete the VM, the node will no longer come back online when restarted, and you will have to register it again on the Great Bear dashboard.

  • To stop the VM, run vagrant down
  • To restart the VM, run vagrant up
  • To remove the VM entirely, run vagrant destroy