Core PlatformMoveworks Agent (On-Prem)

Quickstart

The fastest path to a working Moveworks On-Prem Agent with minimum requirements.

View as Markdown

Purpose

This guide is intended to get the Moveworks On-Prem Agent running as quickly as possible with the minimum requirements — one host, one system, basic auth. It is not a production implementation guide and is not specific to ServiceNow. ServiceNow is used here only because it is the most common system available in a lab or demo context.

If your goal is to understand the agent’s full capabilities, security options, or high-availability setup, start with the Installation Guide and Configuration Guides instead.

Using a ServiceNow PDI for testing

The on-prem agent is designed for systems that are not publicly accessible from the internet — internal instances behind a corporate firewall. A ServiceNow personal developer instance (PDI) from developer.servicenow.com is publicly accessible, so it does not technically require an on-prem agent in a real deployment. It is used here because it is freely available and provides a complete end-to-end demo of the setup workflow without needing access to internal infrastructure.

Prerequisites

Before starting, confirm you have the following:

  • A Linux host (Ubuntu 20.04+ or RHEL 8.0+) with outbound internet access
  • Docker Engine installed, or the ability to install it (the setup script handles installation automatically)
  • Administrator access to Moveworks Setup
  • The Org Name (your Customer ID) from Moveworks Setup > Organization Information
  • A ServiceNow instance URL and admin credentials

Minimum host requirements:

  • 2 CPUs
  • 4 GB RAM
  • 30 GB disk space

Outbound network access required to:

  • https://agent.moveworks.com (US Commercial)
  • https://public.ecr.aws (to pull the agent container image)

To verify connectivity from your host:

$curl https://agent.moveworks.com/api/v1/auth
$# Expected response: 404 page not found

Step 1: Generate the Agent Secret

Before running the installation script, generate the agent secret in Moveworks Setup. The secret authenticates the agent container to the Moveworks platform.

  1. Navigate to Moveworks Setup and search for Agent in the left navigation, or go to Core Platform > On-Premise Agents
  2. Click Generate Secret in the top right corner
  3. Copy the Org Access Secret from the popup and save it securely

The Org Access Secret is displayed only once. Save it before closing the popup. If you lose it, generate a new one — the previous secret will be invalidated.

Step 2: Install the Agent

On your Linux host, run the following commands:

$# Download the setup script
$curl -fsSL https://get-agent.moveworks.com > setup_agent.sh
$
$# Make it executable
$chmod +x setup_agent.sh
$
$# Run the installer (Docker)
$sudo ./setup_agent.sh --docker

The script will:

  1. Install Docker if not already present
  2. Pull the latest Moveworks Agent container image from the public ECR registry
  3. Walk you through configuration prompts

If your host blocks access to public.ecr.aws, see Fetching the Agent Image Without ECR.

Step 3: Configure the Agent

The setup script runs an interactive wizard that generates your agent_config.yml. Answer the prompts as follows for a ServiceNow basic auth setup:

PromptValue
Enter the number of Agents to Start1 (use 2 for production HA)
Enter the agent versionPress Enter to accept the latest
Do you want to configure an external secrets manager?1 (No)
Enter the access_key (org name)Your org name from Moveworks Setup > Organization Information, all lowercase
Enter the access_secretThe Org Access Secret generated in Step 1
Enter the auth_urlhttps://agent.moveworks.com/api/v1/auth
Enter the config_urlhttps://agent.moveworks.com/api/v1/config
Do you want to set up agent to use a proxy?n
Do you want to set up an LDAP connector?n
Do you want to set up a REST connector?y
Enter the service nameSNOW
Do you want to set up a header decorator?y
What type of header decorator?3 (basic auth)
Enter the usernameYour ServiceNow admin username (e.g. admin)
Enter the passwordYour ServiceNow admin password — type it, do not paste

The auth_url and config_url above are for the US Commercial region. Use the correct base for your region:

RegionBase URL
US Commercialhttps://agent.moveworks.com
US GovCloudhttps://agent.moveworksgov.com
EUhttps://agent.am-eu-central.moveworks.com
Canadahttps://agent.am-ca-central.moveworks.com
Australiahttps://agent.am-ap-southeast.moveworks.com

When the wizard completes, the script writes the following to /home/moveworks/agent/conf/agent_config.yml:

1bond_version: 2.10.4  # Auto-set by setup_agent.sh — do not edit
2moveworks_config:
3  access_key: your-org-name
4  auth_url: https://agent.moveworks.com/api/v1/auth
5  config_url: https://agent.moveworks.com/api/v1/config
6  moveworks_access_secret:
7    encrypted_value: <auto-encrypted>
8rest_configs:
9  SNOW:
10    service: SNOW
11    header_decorators:
12    - basic_auth:
13        username: admin
14        password:
15          encrypted_value: <auto-encrypted>

Important: The encrypted_value fields are populated automatically — the script encrypts the credentials you entered. If you ever need to edit the config manually, use value: for any new credential and the agent will encrypt it on next start.

Step 4: Start the Agent

After configuration completes, start the agent containers:

$sudo ./setup_agent.sh --start

Verify the containers are running:

$sudo docker ps

You should see one or more containers named moveworks_agent_1 (and moveworks_agent_2, etc. if you started multiple).

Step 5: Verify the Connection in Moveworks Setup

  1. Navigate back to Core Platform > On-Premise Agents in Moveworks Setup
  2. Confirm the agent appears in the Live Agents tab with a healthy status
  3. The Agent health column should show green once the container has successfully authenticated

It may take up to 60 seconds for the agent to appear after starting.

Step 6: Create the Connector

With the agent running, create a connector in Moveworks Setup to point at your ServiceNow instance.

  1. Navigate to Moveworks Setup > Connectors and select System Connectors (for built-in ServiceNow integrations) or Custom Connectors (for Agent Studio)
  2. Click Create New
  3. Set Auth Config to On Premise Auth
  4. Set Service Name to SNOW — this must exactly match the service name you entered during Step 3
  5. Set Base URL to your ServiceNow instance URL (e.g. https://your-instance.service-now.com)
  6. Save the connector

For LDAP (Active Directory) or more complex configurations, refer to the Configuration File Reference and Configuration Examples.

Common Commands

TaskCommand
Start agent containerssudo ./setup_agent.sh --start
Stop agent containerssudo ./setup_agent.sh --stop
Reconfigure (change org, secret, etc.)sudo ./setup_agent.sh --configure
Upgrade agent to latest versionsudo ./setup_agent.sh --upgrade
Check running containerssudo docker ps
Validate OS and connectivity./setup_agent.sh --validate

Next Steps