Prerequisites

System/Server Requirements

The Moveworks Agent runs on Linux. Recommended OS with the following requirements (which are the same as “t3.medium” if hosted in AWS or a “B2” if hosted in Azure):

4 GB RAM
2 CPUs
30 GB of disk space

OS Requirements:

VM with Ubuntu 20.04 and above OR RHEL 8.0 and above.
Latest Version of Docker Engine or Podman must be pre-installed.

Server Setup

Procure server(s) matching the requirements outlined above. Note: Moveworks recommends at least 2 servers for high availability (HA).
Set up the Server with Docker or Podman. Note: Podman is recommended for a fully root-less implementation.
Recommended: If possible, Moveworks recommends that you use a separate (non-root) user for running the Moveworks Agent. This limits the granting of unintended access rights for the Agent.

Network Requirements

Ensure the server has proper network access to the on-premises system you intend Moveworks to connect to.
Ensure the server has proper network access upstream to the Moveworks Platform.
- Note: You can run the following curl command on the server to verify connection works: curl <auth_url> If Network connection is set up correctly, you should receive 404 page not found as the response.
- auth_url to be used:
  - For US commercial region: https://agent.moveworks.com/api/v1/auth
  - For US GovCloud region: https://agent.moveworksgov.com/api/v1/auth
  - For EU region: https://agent.am-eu-central.moveworks.com/api/v1/auth
  - For Canada region: https://agent.am-ca-central.moveworks.com/api/v1/auth
  - For Australia region: https://agent.am-ap-southeast.moveworks.com/api/v1/auth
- 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/
  - For Australia region: https://agent.am-ap-southeast.moveworks.com/

Credentials and Information Provided by the Customer:

URL of the AD Domain controller or load balancer that the agent should connect to
Active Directory & OpenLDAP service account username & password (Only applicable for customers using on-premises Active Directory or OpenLDAP)
REST Authentication (Only applicable for customers using On-Premise Connections to make REST API Calls i.e. Jira, Confluence, Sharepoint, etc)
Base 64 encoded .pem cert file for LDAPS connection (typically this is the root cert in base64 format)

Moveworks Agent Credentials:

Access Key (Org Name): This is the same as your Customer ID which you should have used when setting up SSO.
Access Secret: To get the Access Secret, you must first generate it from the Agents module in Moveworks Setup:
1. Navigate to the Agents module in the left navigation bar under Core Platform.
1. Click on the Generate Secret button in the bottom right. A pop-up window will appear showing the Org Access Secret.
2. Copy the Org Access Secret and save it. You will need this value for the installation script.
IMPORTANT: Secure Your Org Access Secret
Please be advised that the API token for the Org Access Secret is displayed only once. It is imperative that you save it immediately for future use. Please handle the secret securely, and do not share it in plain text.

Installation Method

Change the directory to where you need to setup the agent. (Home Directory is recommended)

Download the agent installation script using curl or wget (these links redirect to GitHub):

$ curl -fsSL https://get-agent.moveworks.com > setup_agent.sh

$ wget https://get-agent.moveworks.com/ --output-document setup_agent.sh

Set the script’s permissions to allow execution.

$ chmod +x setup_agent.sh

Select the runtime between docker and podman and run the script

Shell

sudo ./setup_agent.sh --docker

Shell

./setup_agent.sh --podman

The script installs Docker or Podman automatically if not already present.

Commands shown with sudo apply to Docker deployments. Omit sudo when using Podman.

To use host network mode (needed if IP forwarding is disabled or the container cannot access the network), append --host-network to the command: sudo ./setup_agent.sh --docker --host-network

Configure the Setup

Example Prompts & Values:

Prompt	Description	Example Values
Enter the number of Agents to Start	At least 2 agents are recommended to be running in a single server.	`1` `2` `3`
Enter the agent version	The version of the agent which you want to install. (default is the latest)	Check latest version from https://gallery.ecr.aws/moveworks/agent
Configuration file found. Do you want to set a new configuration? [y/n]:	This only happens when a configuration file already exists. You can choose to re-configure here.	y/n
Do you want to add required Certificates( If the agent is meant to connect to a Directory system using LDAP)?	You can add Certificates here in the certs directory. Rerun the script for changes to apply.	y/n

If the script fails to fetch the agent image from ECR, see Fetching the Agent Image Without ECR below.

Configuring the Agent

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: `3`, if secrets are stored in Azure Key Vault.	`1` `2` `3`
Enter the access_key (org name):	This will be provided by Moveworks, use all lowercase characters when entering the value	Tenant Settings > General Information > Org Name
Enter the access_secret:	This is the Access Secret that will be provided by Moveworks. If you configured an external secrets manager to store the Access Secret, it will prompt for input, enter secret URI to where the secret is hosted.	Generate this in Moveworks Setup by following the instructions mentioned here.
Enter the auth_url:	Select the `auth_url` depending on data center requirements. Confirm with the Moveworks team, if unsure.	For - US Commercial: `https://agent.moveworks.com/api/v1/auth` US GovCloud: `https://agent.moveworksgov.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` Australia: `https://agent.am-ap-southeast.moveworks.com/api/v1/auth`
Enter the config_url:	Select the `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` US GovCloud: `https://agent.moveworksgov.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` Australia: `https://agent.am-ap-southeast.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` directory	`cert.pem`
Do you want to set up an LDAP connector? Enter [y/n]:	Enter `y` if connecting to Active Directory or OpenLDAP. Enter `n` if you are only setting up REST connectors (e.g. ServiceNow, Jira) — skip all LDAP prompts below.	`y` `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 svc_moveworks` Please note that this may sometimes require escaping, e.g.`MVWKS ame.	`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` directory	`company_cert.pem`
Do you want to use StartTLS (this is usually when using port 389) Enter [y/n]:	If you are using `LDAPS` with port `636`, this should be `n` Only choose `y` if you want to use port `389` with `startTLS` option.	`y` `n`
Do you want to set up a REST connector? Enter [y/n]:	`n` - not needed for LDAP-only integration `y` - setup REST connection	`y` `n`
Enter the service name (Ex. JIRA, CONFLUENCE, CHERWELL, SHAREPOINT, MSTEAMS, MANAGE_ENGINE, SNOW):	Enter an appropriate service name. This name should be representative of the system you are trying to connect to. If you have multiple instances, you can enumerate subsequent service names. (i.e. `JIRA`, `JIRA_2`). Please make note of this name as you’ll need to reference it in further steps.	`JIRA`
Do you want to setup a header decorator? Enter [y/n]:	`y` - in order to set up authentication for the REST connection	`y`
What type of header decorator? [KV pair(1), file(2), basic auth(3), Oauth2 Client Credentials(4), Oauth2 Client Credentials Basic Auth (5), Oauth2 Refresh Token (6), Custom Auth(7)]:	Select the appropriate header decorator (typically for auth). You will then be guided to provide the necessary information for the given header type.	`3`

Create the connector
1. Go to Moveworks Setup
2. Select System Connectors or Custom Connectors depending on if the system you have added is used for a built-in functionality or for an Agent Studio use case.
3. Create Connector
4. Select On Premise Auth as the “Auth Config” and enter the Service Name from Step 6. If you are creating a Agent Studio connector, you must enter the Service Name and have it match the config in the agent from Step 6.
5. Save your connector.

Validating the Installation

Validate OS version and connectivity — checks the OS version, connectivity to Moveworks servers, and required folders and permissions.

$ ./setup_agent.sh --validate

Start the agent

$ sudo ./setup_agent.sh --start

Check agent status — verify the containers are running:

$ # For Docker
$ sudo docker ps
$ 
$ # For Podman
$ podman ps

Fetching the Agent Image Without ECR

In some scenarios, enterprises have Servers with Firewall policies which block the ability for the VM to download the Agent image from ECR and automate the setup process, this is an alternate way to fetch the image in those scenarios.

You can start by visiting the Moveworks ECR Public Gallery and download the latest image tag .

docker pull public.ecr.aws/moveworks/agent:2.10.4

Save this image locally by running the command

docker save -o moveworks_agent.tar public.ecr.aws/moveworks/agent:2.10.4

This will save the image as moveworks_agent.tar

You can then load the image on the customer Server.

docker load -i moveworks_agent.tar

Image should show up on the machine on doing docker images

Now that the image has been added to the VM we can run the below commands to kick off the container.

docker run -d \
  -v /path/to/local/conf:/home/moveworks/agent/conf \
  -v /path/to/local/certs:/home/moveworks/agent/certs \
  -v /path/to/local/logs:/var/log/moveworks \
  -e LOG_LEVEL=INFO \
  public.ecr.aws/moveworks/agent:2.10.4

Other Tools

Stop all running agents — shuts down all running agents.

$ ./setup_agent.sh --stop

Fetch LDAP certificate from the server — requires openssl:

$ openssl s_client -connect <ldap-domain>:<port> -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM > ldap_cert.pem

Reconfigure the agent:

$ ./setup_agent.sh --configure

Upgrade the agent — upgrades all agent containers to the latest version:

$ ./setup_agent.sh --upgrade

Common Errors

If you encounter errors while running setup_agent.sh, see Installation Errors in the Troubleshooting Guide.

Sample Moveworks Agent Configurations

LDAPS only (port 636)

yml

1 bond_version: 2.10.4  # Auto-set by setup_agent.sh — do not edit
2 ldap_config:
3   enabled: true
4   host: mvwks.net
5   ldap_service_password:
6     encrypted_value: [REDACTED]
7   path_to_cert: /home/moveworks/agent/certs/cert.pem
8   port: 636
9   service_user: MVWKS\svc_moveworks
10   use_ssl: true
11 moveworks_config:
12   access_key: moveworks
13   auth_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
14   config_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
15   moveworks_access_secret:
16     encrypted_value: [REDACTED]

LDAPS + Jira

yml

1 bond_version: 2.10.4  # Auto-set by setup_agent.sh — do not edit
2 ldap_config:
3   enabled: true
4   host: mvwks.net
5   ldap_service_password:
6     encrypted_value: [REDACTED]
7   path_to_cert: /home/moveworks/agent/certs/cert.pem
8   port: 636
9   service_user: MVWKS\svc_moveworks
10   use_ssl: true
11 moveworks_config:
12   access_key: moveworks
13   auth_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
14   config_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
15   moveworks_access_secret:
16     encrypted_value:[REDACTED]
17 rest_configs:
18   JIRA:
19     enabled: true
20     header_decorators:
21     - basic_auth:
22         password:
23           encrypted_value: [REDACTED]
24         username: service-moveworks
25     service: JIRA

LDAPS + Jira + Confluence + Azure Key Vault

yml

1 bond_version: 2.10.4  # Auto-set by setup_agent.sh — do not edit
2 ldap_config:
3   enabled: true
4   host: mvwks.net
5   ldap_service_password:
6     azure_entry:
7       secret_name: mw-ldap-secret
8   path_to_cert: /home/moveworks/agent/certs/cert.pem
9   port: 636
10   service_user: MVWKS\svc_moveworks
11   use_ssl: true
12 moveworks_config:
13   access_key: moveworks
14   auth_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
15   config_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
16   moveworks_access_secret:
17     encrypted_value:[REDACTED]
18 rest_configs:
19   JIRA:
20     enabled: true
21     timeout_ms: 60000 #increase default timeout to 60s. Value is in ms
22     header_decorators:
23     - basic_auth:
24         password:
25           azure_entry:
26             secret_name: mw-jira-secret
27         username: jira-moveworks
28     service: JIRA
29   CONFLUENCE:
30     enabled: true
31     header_decorators:
32     - basic_auth:
33         password:
34           azure_entry:
35             secret_name: mw-confluence-secret
36         username: confluence-moveworks
37     service: CONFLUENCE 
38 secrets_provider_config:
39   azure:
40     default_vault: https://agent-dev-vaulxt.vault.azure.net/