> This page is for Tools. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.moveworks.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server. # On-Prem Agent Installation Guide # 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 ` 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` * For Japan region: `https://agent.jp.moveworks.com/api/v1/auth` * For UK region: `https://agent.uk.moveworks.com/api/v1/auth` * For US Prod 4 region: `https://agent.prod4.us.moveworks.com/api/v1/auth` * For US Prod 3 region: `https://agent.prod3.us.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/` * For Japan region: `https://agent.jp.moveworks.com/` * For UK region: `https://agent.uk.moveworks.com/` * For US Prod 4 region: `https://agent.prod4.us.moveworks.com/` * For US Prod 3 region: `https://agent.prod3.us.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. ![](https://files.readme.io/ecfbe3221b2fcae89738fadd61a32b498ea67a4969282c4d5d18e1a2d38c9c5b-image.png) \ 2. Click on the Generate Secret button in the bottom right. A pop-up window will appear showing the `Org Access Secret`. 3. Copy the Org Access Secret and save it. **You will need this value for the installation script.** > **Warning** > > **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 1. Change the directory to where you need to setup the agent. (Home Directory is recommended) 2. Download the agent installation script using `curl` or `wget` (these links redirect to GitHub): ```shell curl -fsSL https://get-agent.moveworks.com > setup_agent.sh ``` ```shell wget https://get-agent.moveworks.com/ --output-document setup_agent.sh ``` 3. Set the script's permissions to allow execution. ```shell chmod +x setup_agent.sh ``` 4. Select the runtime between docker and podman and run the script **`Shell`** ```Text Shell sudo ./setup_agent.sh --docker ``` or **`Shell`** ```Text Shell ./setup_agent.sh --podman ``` The script installs Docker or Podman automatically if not already present. > **Info** > > Commands shown with `sudo` apply to Docker deployments. Omit `sudo` when using Podman. > **Info** > > 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` 5. **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](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
> **Warning** > > If the script fails to fetch the agent image from ECR, see [Fetching the Agent Image Without ECR](/tool-studio/moveworks-agent/moveworks-agent-installation-guide#fetching-the-agent-image-without-ecr) below. 6. 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](/tool-studio/moveworks-agent/moveworks-agent-installation-guide#moveworks-agent-credentials). \
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` Japan: `https://agent.jp.moveworks.com/api/v1/auth` UK: `https://agent.uk.moveworks.com/api/v1/auth` US Prod 4: `https://agent.prod4.us.moveworks.com/api/v1/auth` US Prod 3: `https://agent.prod3.us.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` Japan: `https://agent.jp.moveworks.com/api/v1/config` UK: `https://agent.uk.moveworks.com/api/v1/config` US Prod 4: `https://agent.prod4.us.moveworks.com/api/v1/config` US Prod 3: `https://agent.prod3.us.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`
7. Create the connector 1. Go to Moveworks Setup ![](https://files.readme.io/879740450be8c73ddd88c8fe3252ec71fbce0da2b9f1fc1ffaea96e588eb38fc-CleanShot_2025-01-06_at_20.16.242x.webp) 2. Select System Connectors or Custom Connectors depending on if the system you have added is used for a built-in functionality or for a Tool Studio use case. ![](https://files.readme.io/a459d5eb2365fbd504dd01e59f5203857a88404341c3b3e2f0d0a7d95e33fbb4-CleanShot_2025-01-07_at_17.16.40.png) 3. Create Connector ![](https://files.readme.io/c426e67419c44a39e7e8bbcce9fb5b3c9d2d013c7f228ab157b22c4971bbeb23-CleanShot_2025-01-06_at_20.18.302x.webp) 4. Select On Premise Auth as the “Auth Config” and enter the Service Name from Step 6. If you are creating a Tool Studio connector, you must enter the Service Name and have it match the config in the agent from Step 6. ![](https://files.readme.io/9a686a4191d8c4fd7c9dbddde85cc25ee1dfff8295fe3e5061aa925ae48e0e3b-CleanShot_2025-01-06_at_20.20.392x.webp) 5. Save your connector. ### Validating the Installation 1. **Validate OS version and connectivity** — checks the OS version, connectivity to Moveworks servers, and required folders and permissions. ```shell ./setup_agent.sh --validate ``` 2. **Start the agent** ```shell sudo ./setup_agent.sh --start ``` 3. **Check agent status** — verify the containers are running: ```shell # 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](https://gallery.ecr.aws/moveworks/agent) 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 1. **Stop all running agents** — shuts down all running agents. ```shell ./setup_agent.sh --stop ``` 2. **Fetch LDAP certificate from the server** — requires [openssl](https://www.openssl.org/): ```shell openssl s_client -connect : -showcerts /dev/null | openssl x509 -outform PEM > ldap_cert.pem ``` 3. **Reconfigure the agent**: ```shell ./setup_agent.sh --configure ``` 4. **Upgrade the agent** — upgrades all agent containers to the latest version: ```shell ./setup_agent.sh --upgrade ``` ### Common Errors If you encounter errors while running `setup_agent.sh`, see [Installation Errors](/tool-studio/moveworks-agent/moveworks-agent-troubleshooting#installation-errors) in the Troubleshooting Guide. ## Sample Moveworks Agent Configurations ### LDAPS only (port 636) **`yml`** ```yaml yml bond_version: 2.10.4 # Auto-set by setup_agent.sh — do not edit 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: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED] config_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED] moveworks_access_secret: encrypted_value: [REDACTED] ``` ### LDAPS + Jira **`yml`** ```yaml yml bond_version: 2.10.4 # Auto-set by setup_agent.sh — do not edit 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: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED] config_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED] moveworks_access_secret: encrypted_value:[REDACTED] rest_configs: JIRA: enabled: true header_decorators: - basic_auth: password: encrypted_value: [REDACTED] username: service-moveworks service: JIRA ``` ### LDAPS + Jira + Confluence + Azure Key Vault **`yml`** ```yaml yml bond_version: 2.10.4 # Auto-set by setup_agent.sh — do not edit ldap_config: enabled: true host: mvwks.net ldap_service_password: azure_entry: secret_name: mw-ldap-secret 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: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED] config_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED] moveworks_access_secret: encrypted_value:[REDACTED] rest_configs: JIRA: enabled: true timeout_ms: 60000 #increase default timeout to 60s. Value is in ms header_decorators: - basic_auth: password: azure_entry: secret_name: mw-jira-secret username: jira-moveworks service: JIRA CONFLUENCE: enabled: true header_decorators: - basic_auth: password: azure_entry: secret_name: mw-confluence-secret username: confluence-moveworks service: CONFLUENCE secrets_provider_config: azure: default_vault: https://agent-dev-vaulxt.vault.azure.net/ ```