Skip to main content

Monk in 10 Minutes

This is a super-quick guide to get some containers running within your own Monk cluster, from start to finish.


  • A computer with Linux or macOS installed
  • Open ports 44001 and 44002 for ingress/egress if you're behind a firewall.
  • Have Docker installed and running
  • An account with your favorite cloud provider
  • 10 minutes of your time

Getting Monk#

Install Monk for your OS. For more detailed instructions see Getting Monk.

brew install monk-io/monk/monk

Running Monk#

Ensure that Docker is running on your system. Both Docker and monkd have to be running when using Monk.

Run monkd in a new Terminal window and don't close it:


Wait for it to initialize, and you should get this output:

Monkd v2.4.4ยฉ 2018-2021 OAKds Inc. All rights reserved.
Please stand by while monkd is starting...Initialization complete. monkd is ready

You always need to have monkd running in order to use Monk CLI. Fire it up to continue this guide.

Creating Your Monk Account#

Setting up the account takes 10 seconds. We use accounts to match users with their Monk setups and for licensing and analytics purposes. We are very privacy-focused and only use telemetry data for product improvement. This data never includes your proprietary information. You can learn more about the privacy of Monk accounts.

Use this command to create your Monk account:

monk register

You will be asked to verify your email address before logging in. Check your email!

Signing In#

Once monkd is running and you have confirmed your email address do:

monk login

Use your Monk account email and password:

? Email [email protected]? Password ***** ***โœ” Logged in.

Monk is 100% ready to roll at this point. You will not be asked to log in very often but some commands will require your Monk account credentials.

Creating a Monk Cluster#

Now to the exciting part! Monk cluster is where your workloads will run. Clusters are created once and they serve as a runtime environment that can be grown or shrunk on demand. Let's create a cluster with 3 short commands.

You'll need your service account credentials handy. Here's a reminder on how to get them:

  1. Create a new project in your GCP console,
  2. In the new project, go to IAM → Service Accounts → CREATE SERVICE ACCOUNT
  3. Assign the Admin role on the project to the account,
  4. On the account list, click three dots and create a JSON Key for the account,
  5. Save the file on your machine eg. in key.json

Make sure that the account has compute resources admin access.


Make sure that Compute Engine is enabled on your project. See if you're not sure how.


It's alright if you want to skip cluster creation for now. You can run things locally and create a cluster later. You can still follow this guide but remember that stuff will happen on your machine and not in the cloud. To skip ahead, head to Running templates locally.

To create a new cluster:

monk cluster new

You'll be asked to choose a name for the new cluster. Now we'll attach your cloud credentials to the new cluster:

In order to add your Service Account key to Monk do:

monk cluster provider add -p gcp -f <<path/to/your-key.json>>

where <<path/to/your-key.json>> is an absolute path to your Service Account JSON Key.

For example:

monk cluster provider add -p gcp -f ~/myproject/key.json

Successful invocation will result in:

โœ” Provider added successfully

If you have more cloud accounts you can add all of them. Monk is great at managing singular clusters across cloud providers out of the box.


You don't need to touch, or even have your gcloud or aws CLI installed locally. Monk will work without them being present.


That's it! We now have a brand new cluster. Its only member is your own machine at the moment.

Growing Your New Cluster#

The cluster is there logically. Now we have to expand it physically. Fortunately, we don't have to go back to the cloud console or resort to other tools like Terraform. We will just tell Monk to bootstrap it for us:

monk cluster grow

This command, like all monk commands, can either take arguments or prompt interactively. You will be asked about how many instances you want to spin up - we went with three n1-standard-1. It's generally a good idea to have at least two in your cluster in order to ensure that the cluster remains stable in case of failure of a single node.

Next up, you will be prompted for some information. All fields are required:

? Cloud provider gcp? Name for the new instance foobar? Tag <your-cluster-tag>? Instance region (gcp) us-central1? Instance type (gcp) n1-standard-1? Disk Size (GBs) 20? Number of instances (or press ENTER to use default = 1) 3โ  Creating a new instance(s) on gcp...

Tag is important โ€“ replace <your-cluster-tag> with a name of your choice and write it down. Monk requires all machines in the cluster to be tagged with at least one tag. We will be referring to the new machines by their tag shortly.


Your cloud account may have some quotas on CPU and instance types depending on the region. You may see an error if you hit a quota or choose an unavailable instance-region combination. Try choosing a different region or machine type.

It should take 1โ€“3 minutes to bootstrap all 3 instances. After grow is done, check with:

monk cluster peers

You should get a similar output:

ID     Name      Tag  Cloud ID  Provider  Containers  IP         Started At  Activelocal  local                    unknown   0   52m 3s      true...    foobar-1                 gcp       0           ...        2m 3s       true...    foobar-2                 gcp       0           ...        2m 53s      true...    foobar-3                 gcp       0           ...        3m 1s       true

Sometimes, depending on your network conditions, the peers might appear on the list with a slight delay. Repeat monk cluster peers if you don't see all 3 instances immediately.


You now have a fully operational 3 machine Monk cluster running in your cloud ๐ŸŽ‰

Deploying a Template#

Now that we have a working cluster, it's high time to run something on it.

Use the following command to see what's immediately available:

monk list

Then just pick one of those templates, or just try with mongodb/latest:

monk run -t <your-cluster-tag> mongodb/latest

Remember to replace <your-cluster-tag> with the one you've chosen during monk cluster new!


Skip -t <your-cluster-tag> if you skipped the cluster creation step. The invocation will look like this:

monk run mongodb/latest

Monk will work for a moment and then display a summary showing the current workload layout and some useful hints.


That's it! You're now running stuff, in the cloud, with Monk ๐ŸŽ‰

Cleaning Up#

If you don't want to use the cluster anymore just do:

monk cluster nuke

This will destroy the cluster and all associated resources. Be careful! Monk will not back up the storage of the instances it terminates.

In case you'd like to create another cluster, follow this guide again or see: Creating a cluster.

What's Next?#

Our newly formed cluster has 3 machines and can do much more than just running one simple workload. Having your cluster up and running is enough to start trying everything that Monk has to offer.

If you'd like to try a more advanced setup including a database, HTTP server, and a self-made service, continue to our first A-Z tutorial: Running a small system.

Rate this page