This tutorial will help you install the COSMOS core programs and libraries on a Linux Ubuntu environment. This assumes you already have Ubuntu installed (natively, via Virtual Box or WSL). If you're on the macOS you can also follow these instructions.


COSMOS depends on Git, CMake 2.8.12+ and Build Essential to function.

  • Git
  • CMake 2.8.12+
    • A cross-platform tool to manage building source code.
    • To learn more about Cmake follow the documentation links on the official Cmake page
  • Build essential packages
    • Compilers (gcc, g++ and their dependencies) that builds COSMOS code.

Before anything else make sure that you have all the dependencies you need by running the following commands in a terminal window:

sudo apt update && sudo apt upgrade -y
sudo apt-get install git cmake build-essential -y

Build COSMOS Core

Add your ssh key to

cat ~/.ssh/

Accept all questions with return. Only perform this step if you have not already created a key. Copy this text and add it as a ssh key in your github account settings.

Clone the COSMOS installer script:

git clone ~/cosmos

Run the installer script:

cd ~/cosmos
./ developer

Testing COSMOS Core

Let's test the installation of COSMOS by running two software agents (agent_001, agent_002) Run the following commands in a terminal:


Open another terminal, run:


The agents should now be talking to each other. This illustrates the interconnectivity aspect of COSMOS and its ability to piece together heterogeneous systems. If the terminal reported an error while starting the agent command please check if the PATH env variable was set correctly during the installation process.

Alternatively you can start the programs by changing to the cosmos/bin directory and running

cd ~/cosmos/bin

Build COSMOS Core with Qt Creator (Optional)

Install Qt

For Qt Installation process, follow these instructions.

In Qt Creator, click on File > Open File or Project..., and open up the file ~/cosmos/source/CMakeLists.txt.

TODO: a project configuration dialog might show up?

Once the project is finished loading, click the Projects button on the left side of the window, and then click on Desktop, and then click on Build under it.

Make sure the build directory looks something like:


Now you can press CTRL + B (or the hammer icon at the bottom left) to build the project. This can take a while.

All of the executables are now located in the build directory from above. They are nested in a bunch of different folders, but we need to put them together all in the same folder. To do so, run the following command in a terminal (replacing YOUR_USERNAME with your username):

cd /home/YOUR_USERNAME/cosmos/source/build-core-Desktop-Debug
mkdir bin
find ./ -perm /a+x -exec cp {} bin \;

Now you can copy the contents of the /home/YOUR_USERNAME/cosmos/source/core/build-core-Desktop-Debug/bin folder to the /home/YOUR_USERNAME/cosmos/bin folder. There will be a bunch of files already in the destination folder, but you can remove the old ones (those are from the master branch).

Testing COSMOS on Qt Creator

  1. Navigate to the “Projects” tab on the left menu.
  2. Under “Build & Run” on the left menu, click the “Run” under the same kit you built with.
  3. Under the Run category, select agent_001 under the run configuration. To run it, press Ctrl + R.
  4. Now select agent_002 under the run configuration. Again, press Ctrl + R to run it.

The agents should now be talking to each other. This illustrates the interconnectivity aspect of COSMOS and its ability to piece together heterogeneous systems.

Build COSMOS Core on the Command Line

Build COSMOS Core

To build COSMOS, open a terminal and type:

cd ~/cosmos/source/core/build
mkdir linux
./do_cmake linux
cd linux
make -j8
make -j8 install

Switch to the Dev Branch (Optional)

There are many changes present in the COSMOS Core dev branch that are not present in the master branch. To get the newest changes, switch to the dev branch:

cd ~/cosmos/source/core
git checkout dev
git fetch


A path allows easy access to executable programs. Through this method, you will be able to run agents globally; simply add the cosmos/bin folder to the path. Enter into the terminal:

nano ~/.bashrc

This will open up the file containing the directories the shell looks for programs in. Now, add the following line to the bottom of the file:

export PATH="$HOME/cosmos/bin:$PATH"

After you've added that line, press CTRL + S to save the file, and then CTRL + X to exit.

Next, close the terminal window and open up a new one to reload the PATH. You should be able to run the following command to see the usage of the program:


See Also