Instances is a great starting point for taking advantage of self service features and spinning up both VM’s and containers. In Morpheus it may be advisable to cover the definition of a few terms used within the application so as to reduce confusion.

A set of containers or virtual machines that can correlate to a single horizontally scalable entity or a service suite like a database. (It is important to note that an instance can contain one or more containers/vms depending on the instance type and configuration).
Typically a docker container provisioned via a Morpheus Docker host.
Virtual Machine
A virtualized compute server provisioned onto various hypervisor hosts.

The top of the main Instances page shows overall statistic for the listed Instances, including count, status, and resource utilization. You can search for instances by name, or filter by group, instance type, or category.


Instances listed are determined by group access and role permissions.

The Instance list contains important information about each instance, including the instance name, environment tag, instance type icon, ip and port info, instance version, the number of virtual machines or containers in the instance, the group the instance is in, and the cloud or clouds the instance is in.

Creating Instances

The instance catalog is the one stop shop for selecting items to be provisioned and pieced together. It contains not only basic container and vm options but also tailored services for SQL databases, NoSQL databases, cache stores, message busses, web servers, and even full fledged apps. The list contains a lot of items to choose from and they are represented to the user based on what provisioning engines are enabled and integrated in the Morpheus environment.

To get started, simply click the + Add button in the upper right of the Provisioning -> Instances section. A modal will display allowing the catalog to be searched. Once an item is selected it is just a matter of following the steps through the wizard.


The instance catalog can be customized via role based access control thereby restricting access to non sanctioned catalog items, as well as added to via the Provisioning -> Library section. It is completely customizable.

The next step will ask for a Group and Cloud to be selected. The Group is an abstract representation that can contain multiple cloud integrations. These cloud integrations can also be in multiple groups and is also useful for using role based access control to restrict provisioning access and set retainment policies. If the environment is new and these do not yet exist, It may be advisable to refer to the main section on Getting started by setting up some cloud integrations and infrastructure first. The wizard continues by allowing us to choose a name for the instance as well as an environment.


Currently the Environment option is mostly useful for presenting the user with informative metadata around the instance when coming back to it later.

Moving on, it is now time to configure the Instance. Depending on the option that was chosen and the Instance Configuration that is chosen fields will change. This can include cloud specific fields (i.e. Datastore for VMware or Network). There will also be options like initial username. Some of these fields are optional and will be represented as such.

Configuration options provided in this screen are very powerful. An example is Mysql where a Master/Slave or Master/Master layout can be selected. These configurations will automatically deploy two MySQL VMs or containers and link them together to provide replication. These types of configurations exist for a wide range of instance types and are optimized for high performance and scale. It is even possible to provision entire sharded Mongo clusters.

One last step before the instance can be provisioned is the Automation step. This wizard step may or may not appear depending on the capabilities of the instance type or previous configurations in the account. It is here one can easily select a post provisioning workflow to run ( see more on Tasks and Workflows), assign a load balancer, or even configure the backup job that gets created.

Now that the steps are completed for provisioning the selected instance type , simply review your selections and complete. The instance will automatically show up in the instances list and its provisioning state will be represented. Depending on what was provisioned this step can range from seconds to minutes (typically a container configuration will be rather quick if the instance type has previously been provisioned before).

Instance Details

The instance detail page is where you can view and fully manage an instance. To get to an instance detail page, navigate to provisioning, instances, and click on an instance. Please note instance details and actions differ between instance types and user permissions.

There are several sections within an Instance page that provide useful capabilities to the user.

Stats and status information
Track deployment history for instance types that support deployments or manually kick off a deployment (only visible for instance types that support deployments)
Some instance types support custom configuration settings (i.e. mysql presents the my.ini)
Useful for configuring security groups and access to the instance.
Quick summary of the monitoring system and all checks that were configured to test the state of the instance
Quick backup dashboard. Useful for viewing historical backups as well as kicking off new ones.
View all aggregated logs from the containers or VM’s representing the instance.
View the environment variables presented to the instances or exported by the instances via Apps (more on this in the Apps section). Even see Imported environment variables that may be referenced by the running instance.
For instances that support load balancing and auto scaling. Easily configure auto scaling thresholds and load balancer settings that pertain to a particular instance.
Access the instance or container via a client-less Console supporting SSH, RDP, VNC, and even hypervisor level remote consoles.

Managing Instances

Instance actions allow you to perform numerous management tasks on instances. The actions available depend on the instance type, hypervisor, roles permissions, and instance state.

Edit the Name, Description, Environment, Group, Metadata, Tags, and Owner for the Instance.
Deletes the Instance.


Deleting an Instance will delete associated VM’s or Containers and cannot be undone. To delete instances without deleting associated VM’s, delete the VM from the Infrastructure section and uncheck “Remove Infrastructure” while checking “Remove Associated Instances” in the delete modal options.


You can change the owner of an instance easily by selecting the edit button and entering a new owner in the corresponding field.


Available options in the Actions dropdown can include:

Puts the VM in a suspended state without shutting down the OS.
Stop/Start/Restart Service
Stops, Starts or Restarts the service associated with the Instance Type.
Stop/Start/Restart Server
Stops, Starts or Restarts the Virtual Machine.
Lock/Unlock Instance
A locked instance cannot be deleted until it is unlocked.
Import As Image
Creates a Virtual Image Blueprint from the Instance at its current state and adds it to the Virtual Image library with corresponding metadata.
The Reconfigure action allows service plan, disk, cpu, ram, networks and storage controller changes. Available options depend on the instance type and service plan configuration. Some resize actions require an instance restart.
Creates a new Instance from the Instance at its current state.
Immediately executes a backup of the Instance. Only available for Instances with backups enabled.
Run Workflow
Presents workflow options and then immediately runs selected Workflow on the Instance. Workflows can be created in the Provisioning -> Automation section.
Run Script
Presents Script options and immediately executes selected Script on the Instance. Scripts can be created in the Provisioning -> Library section.
Apply Template
Presents Template options and immediately applies selected Template to the Instance. Templates can be created in the Provisioning -> Library section.
Add Node
Adds an additional node to the configuration. Additional options and configurations are required in the add node wizard depending on instance configuration and type.
Eject Disk
Ejects attached disk/iso.
Add Slave
Adds a database slave in the Instance.
Change Master
Changes the database Master node in an Instance.
Clone to Template (VMware)
Creates a new VMware Template from the Instance with corresponding Morpheus Virtual Image record.


Scrolling down in the Actions dropdown may be necessary to see all options.

Edit Instances

Morpheus allows for the ability to edit an instance once it has been provisioned. There are several fields that can be edited.

Add a name to your instance
Add a description to your instance
Tag your instance to an environment for easy filtering of your instances
Assign your instance to a group for visibility and management
Metadata is a key value pair meant for tracking. You can export variables as metadata.
Add tags to easily keep track of instances
Easily assign an owner to an instance

The environment, group and owner fields must be set to previously defined options in Morpheus.

Name, description, metadata and tags are free form fields that allow you to add additional information to your instance.

Performing Instance Actions

  1. Select the Provisioning link in the navigation bar.
  2. Click the Instance from the list of instances you wish to perform an action on.
  3. Click the Actions drop down button and select an Action.


Every Instance has a Notes section for adding useful information about the Instance. Notes can be added by selecting the ADD NOTES button on the bottom of Instance Detail pages. Existing notes can be edited by selecting the EDIT NOTES


Markdown Syntax is supported in Instance Notes.

Remote Console

Morpheus has a built in Remote Console for Instances, Hosts, Virtual Machines and Bare Metal. The following information reviews the Roles Settings, Protocols, and Requirements necessary to configure and troubleshoot Remote Console access.

Role Settings

User Role settings determine if the Console tab or Open Console Action appear for a user, and if a login prompt is presented or the user is automatically logged in when using the Console.

  • Remote Console (None, Provisioned, Full)
    The user will not have access to remote console.
    The user will only have remote console access for Instances they provisioned.
    The user will have remote console access for all instances they have access to.
  • Remote Console: Auto Login (No, Yes)
    A login prompt will be present in the console for Linux platforms, and the main login screen will present for Windows platforms.
    Morpheus will automatically login to the remote console using the credentials defined on the VM or Host. For provisioned Instances, the credentials are defined either from the credentials defined on the Virtual Image used, added via cloud-init or VMware Tools using the global cloud-init settings (Administration - Provisioning) or the Linux or Windows settings defined in User Settings. For Instances created when converting a VM or Host to managed, the credentials are entered when converting to managed. These credentials can be changed by editing the underlying VM or Host of the Instance.


If the credentials defined on the VM or Host are not valid, and the Remote Console: Auto Login Role setting is set to Yes, the console will not be able to connect and no console window or login prompt will be presented. The credentials on the underlying VM or Host must be edited or Remote Console: Auto Login Role setting can be set to No for a login prompt to present in the console. Credentials cannot be changed from an Instance view, only in the Infrastructure VM or Host view.


Platform Type and Cloud Settings determines the protocol and port used for Remote Console connections.

  • SSH
    The SSH protocol will be used for Linux and OSX platform types, and 22 is the default port used.
  • RDP
    The RDP (Remote Desktop) protocol will be used for Windows platform types over port 3389 by default.
  • VNC (VMware Hypervisor Console)
    The VNC protocol will be used for all platform types in VMware Clouds with the Hypervisor Console option enabled in cloud settings. A unique port is assigned per per Virtual Machine starting at 5900.


Alternative ports can be configured per VM or Host by editing the VM or Host and editing the Port field in the RPC host section.


For all Linux and OSX platform types, Morpheus will use the SSH protocol via port 22 by default for Remote Console connections, unless the Hypervisor Console` option is enabled for VMware type clouds.

Morpheus will SSH using the username, password, RPC Host IP address and Port defined in the VM or Host record.

Default Requirements for SSH Connectivity

  • SSH Enabled on the target VM or Host
  • Port 22 incoming open on the target VM or Host firewalls and security groups from the Morpheus Appliance (not from the users IP address)
  • An IP address defined on the VM or Host record that is routable from the Morpheus Appliance.
  • Valid credentials defined on the VM or Host record in the RPC host field.
  • Remote Console Role Permissions set to Provisioned or Full if the User provisioned the instance, or Full if the user did not provision the instance.


For all Windows platform types, Morpheus will use the RDP protocol via port 3389 by default for Remote Console connections, unless the Hypervisor Console` option is enabled for VMware type clouds.

Morpheus will RDP using the username, password, RPC Host IP address and Port defined in the VM or Host record.

Default Requirements for RDP Connectivity

  • Remote Access enabled on the target VM or Host and Remote Desktop enabled in the Windows Firewall settings. If the VM or Host is on a different network than the Morpheus appliance, public access for Remote Desktop must be enabled in the Firewall settings.
  • Port 3389 incoming open on the target VM or Host firewalls and security groups from the Morpheus Appliance (not from the users IP address)
  • An IP address defined on the VM or Host record that is routable from the Morpheus Appliance.
  • Valid credentials defined on the VM or Host record in the RPC host field.
  • Remote Console Role Permissions set to Provisioned or Full if the User provisioned the instance, or Full if the user did not provision the instance.


If Remote Console: Auto Login is set to No in a users Role permissions, Allow connections only from computers running Remote Desktop with Network Level Authentication in the Windows System Properties -> Remote settings must be DISABLED for Remote Console to connect.

VNC (VMware Hypervisor Console)

When the Hypervisor Console option is enabled in VMware cloud settings, the VNC protocol will be used for all platform types that VMware Cloud.

When using VNC Hypervisor Console, the Morpheus Appliance connects directly to the ESXi host the VM is on, not directly to the VM. A VNC port is assigned per Virtual Machine starting at 5900 and a complex VNC password is generated. VNC is then enabled and the port and password are set on the VMs settings in vSphere.

Morpheus features Remote Console support directly to VMware ESXi hypervisors. To enable this feature a few prerequisites must be met:

  • The gdbserver Firewall setting needs to be enabled on each ESXi host the console will connect to. This can be done in vSphere under firewall configuration on the ESXi hosts by checking the gdbserver option on each required host, This will open up the necessary ports VNC ports on the ESXi host(s), starting at port 5900.


The most common cause of Remote Console connection issues when using hypervisor console is gdbserver not being enabled on the ESXi hosts firewall settings.

  • The Morpheus Appliance must have network access to the ESXi hosts within vCenter, specifically to the host the VM is on when using Remote Console, over the VNC port range, typically 5900-6000. The connection does not go through the vCenter server(s).
  • The Morpheus Appliance must be able to resolve the ESXi hostnames.
  • VMware tools or equivalent must be installed on the VM.

Unlike SSH and RDP, valid credentials do not need to be set on the VM or Host records in Morpheus for VNC hypervisor console connections. An IP address is also not required on the VM or Host for VNC hypervisor console connections. Morpheus will be able to connect to the VVM or Host as soon as the Host (Hypervisor) record is set, which can be viewed in the Info section on the VM or Host detail page.


  • Auto-login is not supported for Hypervisor Console. Auto-login role settings do not apply to console connecting when using Hypervisor Console. Please note Hypervisor Console sessions persist on the ESXi host and once a user manually logs in to the VM they will continue to be logged in, even if the console tab/window in Morpheus is closed, until they manually log out.
  • Copy and Paste and Text selection in Linux terminals is not supported when using VNC (VMware Hypervisor Console).
  • In Morpheus versions 3.2.0 and higher, a newer Guacamole version is installed that is not compatible with MacOS Platform Types over VNC. The


All VMs that are inventoried or provisioned into a VMware cloud with Hypervisor Console enabled will have their Console Type set to VNC. Disabling Hypervisor Console will only apply to newly inventoried or provisioned VM’s. VM’s inventoried or provisioned when Hypervisor Console was enabled will continue to use the VNC protocol even after Hypervisor Console is disabled. To revert a VM

Copy and Paste

Copy and Paste for Text is supported for SSH and RDP protocols only.

To Copy text from the console:

  1. Select text in the Console window.
  2. Click the COPY button at the top of the Console window.
  3. The selected text is copied to the users clipboard.

To Paste text into console:

  1. Copy text on the local computer to you clipboard
  2. Right click into the “Paste Text Here” field at the top of the Console window. The field will the display “Text Copied, Use Console to Paste.”
  3. Right click into the console window.
  4. The text is pasted into the VM.



Morpheus uses Apache Guacamole, a clientless remote console. Guacamole is installed on the Morpheus Appliance during the initial reconfigure. In Morpheus versions 3.2.0 and higher, Guacamole 0.9.14 is automatically installed. On Morpheus versions older than 3.2.0, 0.9.9 is installed. The 0.9.14 version is required for VNC Hypervisor Console functionality on ESXi v6.5 and later.

The Guacamole proxy daemon, guacd, is used for all Remote Console connections and must be running for Remote Console functionality.

Troubleshooting guacd

If all console connections are not functioning, the Guacamole proxy daemon (guacd) process may not be running or have a stuck process preventing console connections. This is evident when only the header appears in the console tab/window, and no console window appears below the header and no connection status is show in the console header. The following commands can be used on the Morpheus Appliance to restore console functionality.

morpheus-ctl status
Lists all local Morpheus services including guacd and their states. If guacd is stopped, it will need to be started again for Remote Console to function.
morpheus-ctl start guacd
Starts the guacd process
morpheus-ctl stop guacd
Stops the guacd process
morpheus-ctl kill guacd
Forcefully kills the guacd process
morpheus-ctl restarts guacd
Restarts the guacd process
morpheus-ctl tail guacd
Tails the guacd current and state logs, located by default at /var/log/morpheus/guacd/. This log is useful when troubleshooting console connections, guacamole service status, and to determine the protocol being used for the Remote Console connection.

If guacd continues to stop even after being started, or if guacd is running and no properly configured console connections are functioning, there may be a stuck guacd or multiple guacd processes running, which will need to killed and guacd started again.

To kill all guacd processes on the Morpheus Appliance and start guacd again:

  1. Kill the morpheus gaucd proccess: morpheus-ctl kill guacd

  2. Grep for all running guacd processes: sudo ps -aux | grep guacd and note the guacd pid(s) (minus the process from the grep)

  3. Kill all running guacd processes: kill -9 pid replacing pid with the pid(s) of the target processes

  4. Start guacd again: morpheus-ctl start guacd

  5. Tail the guacd logs to verify guacd is started and listening: morpheus-ctl tail guacd The log output will resemble below when guacd is properly running:

    guacd[16899]: INFO:       Guacamole proxy daemon (guacd) version 0.9.14 started
    guacd[16899]: INFO:       Listening on host, port 4822
  6. Additional information in the guacd logs appears when Morpheus is making a console connection. A successful conneciton will resemble:

    guacd[24725]: INFO: Creating new client for protocol "ssh"
    guacd[24725]: INFO: Connection ID is "$24f67856-f050-4a17-83eb-9101g0cd8869"
    guacd[24743]: INFO: Current locale does not use UTF-8. Some characters may not render correctly.
    guacd[24743]: INFO: User "@63102f19-eff4-412e-b1f9-718405f55782" joined connection "$24f67856-f050-4a17-83eb-9101g0cd8869" (1 users now present)
    guacd[24743]: INFO: Auth key successfully imported.
    guacd[24743]: INFO: SSH connection successful.

Guacamole Version

In Morpheus versions 3.2.0 and higher, Guacamole version 0.9.14 is automatically installed. On Morpheus versions older than 3.2.0, 0.9.9 is installed. The 0.9.14 version is required for VNC Hypervisor Console functionality on ESXi v6.5 and later.

Note Guacamole version 0.9.14 is not compatible with MacOS Platform Types over VNC on ESXi v6.0 or prior (6.5 is supported). If necessary, the guacamole version can be reverted to 0.9.9.

To revert the guacamole version from 0.9.14 to 0.9.9.

  1. Kill guacd - morpheus-ctl kill guacd
  2. Check if any guacd processes are still running ps -aux | grep guac
  3. If so, kill the processes kill -9 pid with id being the actual process id, like 16101.
  4. Go to the guac 0.9.9 directory: cd /var/opt/morpheus/guacamole-server-0.9.9
  5. Run: make install
  6. Start guacd: morpheus-ctl start guacd