The documentation you're currently reading is for version 2.9.1. Click here to view documentation for the latest stable version.

Run From Sources

Environment Prerequisites



apt-get install python-pip python-virtualenv python-dev gcc git make realpath screen libffi-dev libssl-dev
apt-get install mongodb mongodb-server
apt-get install rabbitmq-server


yum install python-pip python-virtualenv python-tox gcc-c++ git-all screen icu libicu libicu-devel openssl-devel

yum install mongodb mongodb-server
systemctl enable mongod
systemctl restart mongod

yum install rabbitmq-server
systemctl enable rabbitmq-server
systemctl restart rabbitmq-server

Optional Requirements


Mistral workflow engine also has its own requirements. For more information, please refer to the Mistral README.

Project Requirements

Once the environment is setup, clone the git repo, and make the project. This will create the Python virtual environment under StackStorm, download and install required dependencies, and run tests:

git clone
cd st2
# Note: Some of the tests rely on the submodules so you need to check them
# out to make sure all the tests will pass locally
git submodule update --init --recursive
make requirements

Configure System User

Create a system user for executing SSH actions:

useradd -d /home/stanley stanley
su stanley
ssh-keygen -f /home/stanley/.ssh/stanley_rsa -t rsa -b 4096 -C "" -N ''

Specify a user for running local and remote SSH actions. See Configure SSH. In st2/conf/, change ssh_key_file to point to the user’s key file:

user = stanley
ssh_key_file = /home/[current user]/.ssh/stanley_rsa


Activate the virtualenv before starting the services:

source virtualenv/bin/activate

Run the following to start EWC:

./tools/ start

It will start EWC components in screen sessions.

Additional commands:

source virtualenv/bin/activate  # Activates the Python virtual environment
tools/ startclean    # Reset and launches all StackStorm services in screen sessions
tools/ start         # Launches all StackStorm services in screen sessions
tools/ stop          # Stops all StackStorm screen sessions and services

If the services are started successfully, you will see the following output:

Starting all st2 servers...
Changing working directory to /home/vagrant/st2/./tools/.....
Using st2 config file: /home/vagrant/st2/./tools/../conf/
Using content packs base dir: /opt/stackstorm/packs
No Sockets found in /var/run/screen/S-vagrant.

Starting screen session st2-api...
Starting screen session st2-actionrunner...
    starting runner  1 ...
No screen session found.
Starting screen session st2-sensorcontainer
Starting screen session st2-rulesengine...
Starting screen session st2-resultstracker...
Starting screen session st2-notifier...

Registering sensors, actions, rules and aliases...

EWC can now be operated using the REST API, EWC CLI, and the st2client Python client library.

Install EWC CLI

The EWC CLI client needs to be installed. It is not necessary to install this into the virtualenv. However, the client may need to be installed with sudo if not in the virtualenv:

cd ./st2client
python develop

Verify Installation

To make sure all the components are installed correctly:

st2 --version
st2 --help
st2 action list
st2 run core.local uname

Additional Makefile targets

  • make all creates virtualenv, installs dependencies, and runs tests
  • make tests runs all the tests
  • make lint runs lint tasks (flake8, pylint)
  • make docs compiles this documentation
  • make clean clears .pyc’s and docs
  • make distclean runs make clean target and also drops virtualenv
  • make requirements installs Python requirements
  • make virtualenv creates an empty virtual environment

Manual Testing

If you only need to test a specific module, it might be reasonable to call nosetests directly. Make sure your virtualenv is active then run:

nosetests -v {project_name}/tests

or if you only want to run a test for specific file or even class or method, run:

nosetests -v {project_name}/tests/{path_to_test_file}/{test_file}.py:{Classname}.{method_name}

What’s Next?

Questions? Problems? Suggestions? Engage!