> 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 full documentation content, see https://docs.moveworks.com/llms-full.txt. # On-Prem Agent Quickstart 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](/agent-studio/core-platform/moveworks-agent/moveworks-agent-installation-guide) and [Configuration Guides](/agent-studio/core-platform/moveworks-agent/moveworks-agent-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:** ```shell curl https://agent.moveworks.com/api/v1/auth # Expected response: 404 page not found ``` ![Connectivity check returning the expected 404 response](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/f0af306eab315ba292385939d48bf319aa9bb3c8d041bdd155fe1fe15303745a/docs/assets/images/agent-quickstart/quickstart_agent_step_1.png) *** ## 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](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/b18245de9a825695785650cded824db461b8f0aebe2e1e23d10b2f93ac964529/docs/assets/images/agent-quickstart/create_agent_secret.png) 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: ```shell # 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: ```shell # Podman (recommended — no root required) ./setup_agent.sh --podman ``` ```shell # 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](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/4ed737b455cfef9c5ec3e1abcd37ae8dad069484fced85abcbbc7d9f56f13aad/docs/assets/images/agent-quickstart/quickstart_agent_step_2.png) If your host blocks access to `public.ecr.aws`, see [Fetching the Agent Image Without ECR](/agent-studio/core-platform/moveworks-agent/moveworks-agent-installation-guide#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. | Prompt | Value | | ----------------------------------------------------- | ---------------------------------------------------------------------------- | | Enter the number of Agents to Start | `1` (use `2` for production HA) | | Enter the agent version | Press 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\_secret | The Org Access Secret generated in Step 1 | | Enter the auth\_url | `https://agent.moveworks.com/api/v1/auth` | | Enter the config\_url | `https://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 name | `SNOW` | | Do you want to setup a header decorator? | `y` | | What type of header decorator? | `3` (basic auth) | | Use NTLM? | `n` | | Enter the username | Your ServiceNow admin username (e.g. `admin`) | | Enter the password | Your 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 bytes | Press 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: | Region | Base URL | | ------------- | --------------------------------------------- | | US Commercial | `https://agent.moveworks.com` | | US GovCloud | `https://agent.moveworksgov.com` | | EU | `https://agent.am-eu-central.moveworks.com` | | Canada | `https://agent.am-ca-central.moveworks.com` | | Australia | `https://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: ```shell cat ~/moveworks/conf/agent_config.yml ``` ![The resulting agent\_config.yml showing the configuration structure with credentials encrypted](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/c1585f4d59033302a6292fb7c6f40a3e619fab42ec84ab25ac5ad4a356c9688e/docs/assets/images/agent-quickstart/quickstart_agent_config_cat.png) 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: ```shell # Podman ./setup_agent.sh --start # Docker sudo ./setup_agent.sh --start ``` Verify the containers are running: ```shell # 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](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/c67d2a8152f230715c462189ee3785bb5d07b432f175115aaebaf7df0096d808/docs/assets/images/agent-quickstart/agent_quickstart_step_4.png) *** ## 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](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/1936d3ba2eb2885e7f7db021a7012456b9da2158345aaad8d2662a54e99b04b8/docs/assets/images/agent-quickstart/agent_quickstart_agent_health.png) *** ## 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](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/81fd92d47b83b8f44447dac61e3af23dda1f76d67e5d6e05a0073ac27cf34529/docs/assets/images/agent-quickstart/agent_quickstart_configurator_on_prem_conector.png) 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](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/9f32172251527cf7bc93b132f967959e4b4bd02a9ee25a6fbbfc45ca2daa24cb/docs/assets/images/agent-quickstart/agent_quickstart_confirm_connection.png) A 200 response confirms the full path is working: Moveworks platform → agent container → ServiceNow instance. *** ## Common Commands | Task | Command | | -------------------------------------- | ------------------------------ | | 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 containers | `podman 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 * [Configuration File Reference](/agent-studio/core-platform/moveworks-agent/moveworks-agent-configuration-guides/configuration-file-reference): full YAML schema with all supported fields * [Configuration Examples](/agent-studio/core-platform/moveworks-agent/moveworks-agent-configuration-guides/configuration-examples): sample configs for LDAP, Jira, Azure Key Vault, and more * [Operations and Health](/agent-studio/core-platform/moveworks-agent/operations-maintenance-guide): monitoring, upgrades, and troubleshooting * [Secrets Management](/agent-studio/core-platform/moveworks-agent/moveworks-agent-configuration-guides/secrets-management): storing credentials in AWS Secrets Manager or Azure Key Vault