Core PlatformMoveworks Agent (On-Prem)

On-Prem Agent Quickstart

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

View as Markdown

This guide gets the Moveworks On-Prem Agent running as quickly as possible — one host, one system, basic auth. It uses ServiceNow as the target system because it is the most common system available in a lab or demo context (a free personal developer instance works fine). For production setup, high availability, or non-ServiceNow systems, see the Installation Guide and Configuration Guides.

Prerequisites

Before starting, confirm you have:

  • A Linux host (Ubuntu 20.04+ or RHEL 8.0+) with outbound internet access
  • Podman installed (recommended), or Docker Engine — the setup script can install either 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)

Verify connectivity from your host before proceeding:

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

Connectivity check returning the expected 404 response

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

On-Premise Agents page in Moveworks Setup — click Generate Secret in the top right

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 for your container runtime:

$# Podman (recommended — no root required)
$./setup_agent.sh --podman
$# Docker
$sudo ./setup_agent.sh --docker

Podman is recommended because it runs rootless, without requiring sudo. If you’re unsure which runtime your host uses, check with your system administrator.

The script will:

  1. Install Podman or Docker automatically if not already present
  2. Pull the latest Moveworks Agent container image from the public ECR registry
  3. Walk you through configuration prompts (covered in Step 3)

The setup script downloading and installing Podman automatically

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:

If you are re-running the script, you will see an extra prompt: “Configuration file found. Do you want to set a new configuration? [y/n]” — enter y to reconfigure.

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 setup a header decorator?y
What type of header decorator?3 (basic auth)
Use NTLM?n
Enter the usernameYour ServiceNow admin username (e.g. admin)
Enter the passwordYour ServiceNow admin password — type it, do not paste
Do you want to setup another header decorator?n
Do you want to setup a body decorator?n
Do you want to setup a URL decorator?n
Do you want this REST client to connect with a cert?n
Enter the response size limit in bytesPress Enter to accept the default (50 MB)
Do you want to set up another REST connector?n
Do you want to set up a Moveworks proxy?n
Do you want to add required Certificates (LDAP)?n

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 your configuration to ~/moveworks/conf/agent_config.yml (where ~ is the home directory of the user who ran the script). You can inspect it with:

$cat ~/moveworks/conf/agent_config.yml

The resulting agent_config.yml showing the configuration structure with credentials encrypted

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 the configuration wizard completes, start the agent containers:

$# Podman
$./setup_agent.sh --start
$
$# Docker
$sudo ./setup_agent.sh --start

Verify the containers are running:

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

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

setup_agent.sh --start followed by podman ps showing both containers running

Step 5: Verify the Agent in Moveworks Setup

  1. Navigate back to Core Platform > On-Premise Agents in Moveworks Setup
  2. Confirm your agents appear in the Live Agents tab with Agent Status: Enabled

It may take up to 60 seconds for the agents to appear after starting. The Agent health column will show Not in use when idle — this is normal and does not indicate a problem. It becomes active when a request is being proxied.

Live Agents tab showing both containers registered and Enabled

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
  2. Select Custom Connectors (for Agent Studio use cases) or System Connectors (for built-in ServiceNow integrations)
  3. Click Create New
  4. Fill in the connector form:
    • Connector Name: a unique name for this connector (e.g. now_agent)
    • Base URL: your ServiceNow instance URL (e.g. https://your-instance.service-now.com)
    • Authentication Type: select On-Premise Auth
    • Service Name: enter SNOW — this must exactly match the service name you configured in Step 3
  5. Save the connector

Connector creation form showing On-Premise Auth type and SNOW service name matching the agent config

The Service Name field must exactly match what you entered during Step 3. If you used SNOW in the agent config, enter SNOW here — case-sensitive.

Step 7: Verify in API Playground

Use the API Playground to confirm the connector is routing requests through the agent successfully.

  1. Navigate to Moveworks Setup > API Playground
  2. In the API Collection panel on the left, find Service Now API: Users and select GET /api/now/table/sys_user
  3. In the Connector dropdown, select the connector you just created (e.g. now_agent)
  4. Click Test
  5. Confirm you receive a Status Code: 200 response with ServiceNow user data in the JSON body

API Playground showing a successful 200 response from ServiceNow via the on-prem agent connector

A 200 response confirms the full path is working: Moveworks platform → agent container → ServiceNow instance.

Common Commands

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

If using Docker instead of Podman, prefix setup_agent.sh commands with sudo and use sudo docker ps to check containers.

Next Steps