> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.moveworks.com/agent-studio/core-platform/moveworks-agent/llms.txt.
> For full documentation content, see https://help.moveworks.com/agent-studio/core-platform/moveworks-agent/llms-full.txt.

# Quickstart

<Callout intent="info">
  **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](/agent-studio/core-platform/moveworks-agent/moveworks-agent-installation-guide) and [Configuration Guides](/agent-studio/core-platform/moveworks-agent/moveworks-agent-configuration-guides) instead.
</Callout>

<Callout intent="note">
  **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.
</Callout>

***

## 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:

```shell
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

<Callout intent="warning">
  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.
</Callout>

***

## 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 (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

<Callout intent="info">
  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).
</Callout>

***

## 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:

| 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 set up a header decorator?             | `y`                                                                          |
| What type of header decorator?                        | `3` (basic auth)                                                             |
| Enter the username                                    | Your ServiceNow admin username (e.g. `admin`)                                |
| Enter the password                                    | Your ServiceNow admin password — type it, do not paste                       |

<Callout intent="info">
  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` |
</Callout>

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

```yaml
bond_version: 2.10.4  # Auto-set by setup_agent.sh — do not edit
moveworks_config:
  access_key: your-org-name
  auth_url: https://agent.moveworks.com/api/v1/auth
  config_url: https://agent.moveworks.com/api/v1/config
  moveworks_access_secret:
    encrypted_value: <auto-encrypted>
rest_configs:
  SNOW:
    service: SNOW
    header_decorators:
    - basic_auth:
        username: admin
        password:
          encrypted_value: <auto-encrypted>
```

<Callout intent="warning">
  **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.
</Callout>

***

## Step 4: Start the Agent

After configuration completes, start the agent containers:

```shell
sudo ./setup_agent.sh --start
```

Verify the containers are running:

```shell
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](/agent-studio/core-platform/moveworks-agent/moveworks-agent-configuration-guides/configuration-file-reference) and [Configuration Examples](/agent-studio/core-platform/moveworks-agent/moveworks-agent-configuration-guides/configuration-examples).

***

## Common Commands

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

***

## 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