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

##VMX: The object detection/recognition server

VMX makes computer vision easy.  Docker makes bundling complex
applications easy.  The vmx-docker-manager lets you run the VMX
Object Detection server on a Linux computer, or a (Mac/Windows)
machine via boot2docker. 

##Requirements 64 bit Linux and Docker >= 1.2, root permissions to run Docker boot2docker for Mac or Windows


Either clone the repo

git clone

Or download the shell script directly:


    start PORT: Start vmx on localhost:PORT
    stop:       Stop vmx
    enter:      Shell access to a Docker container for inspecting volumes
    init :      Download and start the containers that have the pre-reqs, mcr, etc.
                (This is done automatically the first time you start vmx)
    update TAG: Update your vmx (will stop vmx first). TAG must be
                "latest" or "dev", defaults to "latest" when TAG is empty
    backup BACKUP: Backup your vmx data (models and config file) to folder BACKUP
    restore BACKUP: Restore from a backup        

##Example: Run vmx on port 3000

$  ./vmx start 3000

Stop vmx

$ ./vmx stop

Backup your data to vmx-docker-manager/.vmx-backup/

$  ./vmx backup

Restore from a backup

$  ./vmx restore .vmx-backup/2014_FriNov21_20_04

Update vmx to latest (stable) version

$  ./vmx update


$  ./vmx update latest

Update vmx to dev version

$  ./vmx update dev


vmx-docker-manager uses Docker which requires permission to run as root, or the user to be added to the docker group.

To make sure Docker is installed and running correctly on your machine, you can first try a simple Docker command such as:

docker run -t -i --rm ubuntu echo "Docker runs"


vmx-docker-manager automatically downloads all dependencies. In general, VMX requires a few files/folder to be available:

  • MATLAB MCR (Matlab Compiler Runtime)
  • Mount points for:
    • Session Information
    • Local Model storage
  • Certain open source libraries

The VMX Docker manager is a set of sane defaults and configurations that store user data (session and models) in seperate volumes at /vmx/sessions and /vmx/models; and loads the binaries into /vmx/build. Those mount points, along with the matlab MCR dependency are run within the context of an Ubuntu 14.04 with the required libraries.

The Dockerfiles that build the referenced Docker images can be found here:

Downloading and sharing VMX models


    download [a] [b] [c]: Download models from remote server into incoming folder
    import:   Import models from incoming folder into VMX container
    upload model_name:   Upload models to a remote location via SSH

 - Download all publicly available models from
    $  ./models download -all

 - Download a,b,c from
    $  ./models download a b c

 - Import downloaded models into local VMX
    $  ./models import

 - Upload a model called gesture-pack-12
    $  ./models upload gesture-pack-12

Extra: Running VMX over HTTPS

If you are a administrator and you want to run VMX on a subdomain such as, you'll need to checkout the branch of the vmx-docker-manager

cd ~
git clone
cd vmx-docker-manager
git checkout
./vmx start 3000

What the branch does is the following: make sure that VMX is only accessible from, and set the VIRTUAL_HOST environment variable.

You should also use the private nginx-ssl-proxy script as follows:

cd ~
git clone
cd nginx-ssl-proxy

Extra (v2): Accessing the ports of the underlying VMXworkers

As of VMX v2, the VMXworker API is the same and the main VMX REST API, the endpoints are just different. When using VMX REST API, your endpoints will look like localhost:3000/sessions/myid/create but if you have the correct port (8099 in this example) you can access the endpoint as localhost:8099/create.

To get the IP of the vmx-environment container, run:

cd ~/vmx-docker-manager/
docker inspect --format='{{.NetworkSettings.IPAddress}}' vmx-environment

To get all PORTS, run

docker run --name vmx-tmp --rm --volumes-from vmx-userdata:ro ubuntu bash -c "cat /vmx/sessions/*/url"

To get the PORT of a session called "tomsession"

docker run --name vmx-tmp --rm --volumes-from vmx-userdata:ro ubuntu bash -c "cat /vmx/sessions/tomsession/url"