Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time



Join the chat at Build Status

Nmesos is a command line tool that leverages the Singularity API to deploy services and schedule jobs in an Apache Mesos cluster.



Using asdf ...

asdf plugin-add nmesos
asdf list-all nmesos
asdf install nmesos <version>
asdf global nmesos <version>
asdf uninstall nmesos <version>

Note: For this to work you need to have asdf 0.8 installed. 0.7 will not work.

Using brew ...

brew tap ninesstack/nmesos
brew install nmesos
brew upgrade nmesos
brew uninstall nmesos

Using curl ...

curl<version>/nmesos-<version>.tgz | tar -xz
chmod 755 nmesos-<version>/nmesos
mv nmesos-<version>/nmesos <to-dir-on-your-path>


There are example configurations in the example directory.

Please run nmesos help to see/understand the commands and options.

To release the example-service from the examples directory you would run ...

nmesos release example-service --environment dev --tag latest --dry-run false

Note: You need to cd into the example directory first. If you want to run nmesos and use configurations that are in a different directory you need to use the NMESOS_CONFIG_REPOSITORY environment variable ...

NMESOS_CONFIG_REPOSITORY=<dir> nmesos release example-service --environment dev --tag latest --dry-run false

Support to deprecate env_vars

When you do not need an env_var anymore, it is hard to remove it from the deployment config right away, because you might need to rollback to a previous version of the service that still needs that env_var (and yes, strictly speaking you could say that the deployment config should/could also be rolled back, but then you might loose other changes that you had to make to the config and ... my experience is you do not want to fiddle with that while you are in the middle of a production outage).

To make this easier/work nmesos supports an annotation to deprecate env_vars ...

nmesos_version: '0.2.20'
    memoryMb: 128

    image: hubspot/singularity-test-service
      - 8080
      ServiceName: "exampleServer"
      OLD_ENV_VAR: "old value" # @deprecated-on 01-Jan-2020
      NEW_ENV_VAR: "new value"

    healthcheckUri: "/hello"

The date is the date, when you deprecated the env_var. nmesos checks the date to find env_vars, where the grace period is expired. The default for the --deprecated-soft-grace-period is 14 days. The default for the --deprecated-hard-grace-period is 28 days.

When the soft-limit is reached a warning is printed. When the hard-limit it reached an error is printed and the deploy is aborted.

The default can be overriden with command line flags (see nmesos help).

Support to run containers locally

To run containers locally you can generate a <service-name>.env file and a docker-compose.<service-name).yml with the docker-env command.

You can then start the service with docker-compose --file docker-compose.<service-name>.yml (to start it in the background just use the --detach flag).

You can also have nmesos run docker-compose for you with the docker-run command (it will start the service in the background).


You can set/export the NMESOS_LOG_LEVEL environment variable. Valid log-levels are error, warn, info and debug. This will log to stdout. You can also set NMESOS_LOG_APPENDER to file. This will create an nmesos.log file in the current directory.