Moveworks Agent Installation Guide
This document walks through the steps to install the Moveworks agent
Prerequisites
Provided by the Customer:
- URL of the AD Domain controller or load balancer that the agent should connect to
- LDAP/AD Service account username & password (Only applicable for customers using On-Premises Active Directory, LDAP, etc)
- REST Service account username & password (Only applicable for customers using On-Premise Jira, Confluence, Sharepoint, etc)
- Firewall rules or HTTP Proxy settings in place to allow for outbound communication to
https://public.ecr.aws
and, to the Agent URL depending on region:
For US commercial region:https://agent.moveworks.com/
For US GovCloud region:https://agent.moveworksgov.com/
For EU region:https://agent.am-eu-central.moveworks.com/
For Canada region:https://agent.am-ca-central.moveworks.com/
- Base 64 encoded .pem cert file for LDAPS connection (typically this is the root cert in base64 format)
- Two virtual machines per recommended specifications for High Availability setup (see System/Server Requirements section)
Pre-Installation Steps:
- Install the latest version of Docker or Podman on the server.
- Ensure the Docker daemon is configured to start on startup
Provided by the Moveworks Customer Success Team:
- Org name
- Org Access Secret
Installation
Following the receipt of the encrypted email from your Moveworks Customer Success Team, proceed with the following steps to install the Moveworks agent on your Linux virtual machine(s).
Podman customers
If using
podman
instead ofdocker
, substitutepodman
for all of the docker commands in the following instructions
- Pull Container Image from Public ECR Repository: Retrieve the latest Docker image of the agent from the public AWS ECR (Elastic Container Registry) repository by running the following command:
docker pull <version>
In the command above replace <version>
with the latest version from the public ECR Repo. You can click the copy button on the link above, to grab the latest version.

- Copy the helper script from the container to your virtual machine by running the following commands
docker create --name temp <version> # create a readable container layer
docker cp temp:/moveworks/services/bond/runtime/scripts/helper.sh ./helper.sh # copy the file from the temp layer
docker rm -f temp # remove the temp layer
- Setup Agent folders & permissions (Note: Some of these operations may require administrative privileges (sudo) to complete.)
./helper.sh --init # This creates a folder structure for storing agent configs, logs, etc.
sudo ./helper.sh --permissions # This ensures proper permissions are set on the VM for the agent to run
-
Configure the Agent: Run the command
./helper.sh --configure
This command initiates an interactive guide to help you through the configuration process by asking you the questions in the table below. This step enables you to provide specific settings and preferences for the agent's operation. Note: This step is not required if you have received a pre-configured configuration file from your Moveworks Customer Success team. In this case, simply place the configuration file in theconf
directory.Example Prompts & Values:
Prompt Description Example Values Do you want to configure an external secrets manager? [No(1), AWS Secrets Manager(2), Azure Key Vault(3)]: Select an option depending on how the service account credentials are created. For example: 1
, if account is created on Active Directory.1
2
3
Enter the access_key (org name): This will be provided by your Customer Success team, use all lowercase characters when entering the value Value provided by Moveworks
Enter the access_secret: This is the Moveworks secret that will be provided by your Customer Success team.
If you configured an external secrets manager it’ll prompt for the secret URI to where the secret is hosted.Value provided by Moveworks
Enter the auth_url: Select an auth_url
depending on data residency requirements. Confirm with the Customer Success team, if unsure.For -
US Commercial:https://agent.moveworks.com/api/v1/auth
Canada:https://agent.am-ca-central.moveworks.com/api/v1/auth
EU:https://agent.am-eu-central.moveworks.com/api/v1/auth
Enter the config_url: Select a config_url
depending on data residency requirements. Confirm with the Customer Success team, if unsure.For -
US Commercial:https://agent.moveworks.com/api/v1/config
Canada:https://agent.am-ca-central.moveworks.com/api/v1/config
EU:https://agent.am-eu-central.moveworks.com/api/v1/config
Do you want to set up agent to use a proxy? Enter [y/n]: optional, default is n
y
n
Enter the proxy url (leave blank for transparent proxies): Do you want to use a cert with the proxy? Enter [y/n]: y
n
[y] Enter the full name of the pem file including the extension: Enter the full filename of your cert and place the cert in /certs
directorycert.pem
Do you want to set up an LDAP connector? Enter [y/n]: Enter y
, if setting up an Active Directory connectiony
n
Do you want to set up an LDAP forest? Enter [y/n]: Select this option to configure multiple ldap domains. This will repeat the next few steps depending on how many domains you want to setup. y
n
Enter the FQDN of the LDAP server (do not include ldap:// prefix): No protocol prefix or port needed. company.net
Enter the port to use e.g: 389 (LDAP), 636 (LDAPS), 3268 (LDAP Global Catalog), 3269 (LDAPS Global Catalog): Moveworks recommends port 636 for LDAPS, you can use port 389 for LDAP for testing purposes during the initial setup. 636
Enter the LDAP service account username: For Active Directory, LDAP Service User is formatted as a netbios domain name with a backlash and then the service account name. MVWKS\\svc_moveworks
Enter the ldap service password: Please type (do not paste) the password. This is then encrypted before being saved to disk. The password is masked on entry so you will not see characters as you type. service account password Do you want to set up LDAP to connect with SSL? Enter [y/n]: y
will allow you to add the local path to your cert (.pem
file)y
n
Do you want LDAP to connect with a cert (.pem file)? Note: this is required for LDAPS connections Enter [y/n]: y
will allow you to add the local path to your cert (.pem
file)y
n
Enter the full name of the pem file including the extension: Enter the full filename of your cert and place the cert in /certs
directorycompany_cert.pem
Do you want to use StartTLS (this is usually when using port 389) Enter [y/n]: If you are using LDAPS
with port636
, this should ben
Only choosey
if you want to use port389
withstartTLS
option.y
n
Do you want to set up a REST connector? Enter [y/n]: n
- not needed for LDAP-only integrationy
- setup REST connectiony
n
Enter the service name (Ex. JIRA, CONFLUENCE, CHERWELL, SHAREPOINT, MSTEAMS, MANAGE_ENGINE, SNOW): Enter the appropriate service name. JIRA
Do you want to setup a header decorator? Enter [y/n]: y
- in order to set up authentication for the REST connectiony
What type of header decorator? [KV pair(1), file(2), basic auth(3), Oauth2 Client Credentials(4), Oauth2 Client Credentials Basic Auth (5), custom auth(6)]: Select the appropriate header decorator (typically for auth).
You will then be guided to provide the necessary information for the given header type.3
-
Add required certificates: If the agent is meant to connect to a Directory system using LDAPS then add the root certificate to the following directory as a
.pem
file/moveworks_agent/certs
. -
Start the Agent: This command starts the agent on the customer VM.
./helper.sh --start
- Verify the agent has started successfully by running
docker ps

Also, ensure that there are no errors in the agent logs by running tail -f logs/moveworks.agent.<container_id>.INFO.log
- Start a second Agent: Once you have verified the Moveworks agent has started successfully, Moveworks recommends starting another agent so that there are at least 2 agents running on the VM. This helps improve stability and reliability of the agent.
Note: For ServiceNow Connections
If you are routing ServiceNow traffic through your Moveworks agent, Moveworks recommends running 4 VMs with 1 agent each.
Helpful Tools
Some helpful scripts are shipped as part of a helper script in the agent package.
-
Validate OS version & Connectivity - This command will validate the operating system version, check for connectivity to Moveworks servers, and ensure required folders and permissions are set.
./helper.sh --validate
-
Stop all running agents — This will shut down all running agents.
./helper.sh --stop
-
Fetch LDAP certificate from the server (openssl required for this script to work)
./helper.sh --fetch
Reconfiguring the Agent
If you need to edit the config simply open the config file with a text editor and edit the fields you need.
- Navigate into into the
conf
directory e.g:cd conf
- Open the
agent_config.yml
with your favorite text editor such as vi or nano e.g:vi agent_config.yml
For sensitive fields like passwords, simply remove the encrypted_value
field and replace it with the value
field and the actual value in plaintext (this will automatically get encrypted on startup of the agent).
moveworks_config:
...
moveworks_access_secret:
value: newsecretvalue
ldap_config:
...
ldap_service_password:
value: newldappassword
Updating the Agent
-
Stop currently running agents. You can use the script under the tools directory.
./helper.sh --stop
-
Pull the latest docker image from ECR public repo.
docker pull <version>
-
Initialize the agent - Run the init command to rename the version as the latest.
./helper.sh --init
-
Restart the Moveworks agent - If there were multiple agents running just run this command again to start additional agents.
./helper.sh --start
-
Verify the agents have started up successfully - Run
docker ps
to ensure the agents are healthy. -
Verify there are no errors in the logs
tail -f logs/moveworks.agent.<container_id>.INFO.log
Sample Moveworks Agent Configurations
LDAPS only (port 636)
bond_version: 2.8.5 # This will be set automatically by the configuration tool
ldap_config:
enabled: true
host: mvwks.net
ldap_service_password:
encrypted_value: [REDACTED]
path_to_cert: /home/moveworks/agent/certs/cert.pem
port: 636
service_user: MVWKS\svc_moveworks
use_ssl: true
moveworks_config:
access_key: moveworks
auth_url: asdf
config_url: asdf
moveworks_access_secret:
encrypted_value: [REDACTED]
LDAPS + Jira
bond_version: 2.8.5 # This will be set automatically by the configuration tool
ldap_config:
enabled: true
host: mvwks.net
ldap_service_password:
encrypted_value: [REDACTED]
path_to_cert: /home/moveworks/agent/certs/cert.pem
port: 636
service_user: MVWKS\svc_moveworks
use_ssl: true
moveworks_config:
access_key: moveworks
auth_url: asdf
config_url: asdf
moveworks_access_secret:
encrypted_value:[REDACTED]
rest_configs:
JIRA:
enabled: true
header_decorators:
- basic_auth:
password:
encrypted_value: [REDACTED]
username: service-moveworks
service: JIRA
Updated 15 days ago