Setting up SIMOC

Initial Setup

For SIMOC users

These instructions explain how to set up SIMOC locally on a Linux machine. You will need to install the SIMOC backend (simoc) and optionally the web frontend (simoc-web).

  1. Create a GitHub account, request access to the repos, and then generate a personal access token.

  2. Clone the SIMOC repositories using the following commands (enter your GitHub username and personal access token when asked):

    git clone
    git clone  # optional

    The simoc-web repository is only needed for the web frontend.

  3. (Optional) To set up the web frontend run:

    cd simoc-web
    python3 setup
  4. To set up the backend run:

    # cd ..  # return to parent dir if you are in simoc-web/
    cd simoc
    python3 setup
  5. Access SIMOC at http://localhost:8000/.


During the setup of either the frontend or backend (steps 3/4), you might be asked to log out and log in again (or restart your machine). After logging back in, you can resume the installation by running the same command again.

For SIMOC developers

  1. Generate and upload an SSH key.

  2. Clone the SIMOC repositories:

    git clone
    git clone  # optional
    git clone  # optional
  3. Follow steps 3-5 from the section above.

For more information see also Repository setup.


You can use the script to control SIMOC:

  • Initial setup: setup

  • Remove SIMOC: teardown

  • Reinstall: reset

  • Start/update the containers: up

  • Stop/remove the containers: down

  • Show the help: --help

Please refer to the --help for the full list of commands.

Running the dev backend

When you start SIMOC, it will use the code included in the containers retrieved from Docker Hub. If you want to run the clone from your local repository, you can use:

python3 --with-dev-backend

This will mount the local directory in the container, so that every change you did to the source will be applied. Since the directory is shared, you can keep making changes and they will automatically be reflected within the container, but you might need to restart the containers using restart.

Using a custom agent_desc.json

It is also possible to specify a custom agent_desc.json file:

python3 --agent-desc agent_desc.json reset-db

This will override the agent_desc.json file in the container with the file specified after the --agent-desc option. Since the file must be loaded in the DB, the reset-db command is used to reinitialize the DB.

If you want to return to the original version of the file, simply run:

python3 reset-db