Skip to main content

Getting Monk

Here's how you install, test, and upgrade Monk.


Monk requires Docker to be present and running on your system. If you don't have Docker installed and running, please refer to and follow the steps detailed there in order to obtain Docker before installing Monk.

Installing Monk#

Installing with Homebrew

We provide a Homebrew repository containing official releases of Monk. You can obtain the latest stable version of Monk from this repository by running the following command:

brew install monk-io/monk/monk

Now run the Monk daemon in a fresh terminal:


monkd has to be running at all times when using monk or running any workloads via Monk. You might consider adding monkd to your launchctl configuration so that it stays running as a service. See Running monkd as a service.


All done! Go to Testing the installation to try it out.

Testing Your Setup#

In a new terminal, run:

monk login

After logging in, you should be able to list the available templates like so:

monk list

The command should return available templates if the installation was successful, but sometimes it may take up to 30 seconds to sync the templates. If you don't see a list at first, just retry in a few seconds.

Type      Template              Repository    Version   Tagsrunnable  chatwoot/chatwoot     local         latest    self hosted, messaging, communicationrunnable  chatwoot/mailhog      monk          latest    smtp, emailrunnable  chatwoot/sidekiq      local         latest    self hosted, messaging, communicationgroup     chatwoot/stack        monk          latest    self hosted, messaging, communication....

If you see similar output it means that the installation was successful and you may now start using Monk on your system ๐ŸŽ‰

Continue to the Guides section to see how you can use Monk.

If for some reason the command didn't work, please check if you have followed all instructions.

Upgrading Monk#

Upgrading your local Monk to the newest version is simple.

brew upgrade monk

If you have a cluster running:

  1. Make sure you are connected to the cluster,
  2. Make sure your local Monk is the latest version,
  3. Run monk system upgrade to upgrade all the nodes to the newest version.

Installation Impact#

Monk aims to be a good steward of your filesystem and not scatter files throughout the disk. The Monk distribution is simple and consists of two binaries, monkd and monk.

When installing with apt or brew those are placed or symlinked in /usr/local/bin. apt on Linux configures your systemd to start monkd as a service immediately after install and on system startup. Additionally, a monkd user group is created and assigned appropriately.

All data files needed for Monk's operation are created in /var/lib/monkd (Linux) and ~/.monk (both Linux and macOS) upon first monkd startup.

The monk command will install bash and zsh autocompletion in your dotfiles on first use. Changes to the dotfiles are reversed upon package removal.

Rate this page