> 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 Operations and Health

# Common Commands

> **Info**
>
> Commands shown with `sudo` apply to Docker deployments. Omit `sudo` when using Podman — see the [Installation Guide](/tool-studio/moveworks-agent/moveworks-agent-installation-guide) for details.

| Task                                        | Command                                 |
| ------------------------------------------- | --------------------------------------- |
| Start agent containers                      | `sudo ./setup_agent.sh --start`         |
| Stop agent containers                       | `sudo ./setup_agent.sh --stop`          |
| Reconfigure (credentials, URLs, connectors) | `sudo ./setup_agent.sh --configure`     |
| Upgrade to the latest version               | `sudo ./setup_agent.sh --upgrade`       |
| Validate OS and connectivity                | `./setup_agent.sh --validate`           |
| Check running containers                    | `sudo docker ps`                        |
| Follow live container logs                  | `docker logs -f <container_name>`       |
| Tail agent log files                        | `tail -f /var/log/moveworks/*.INFO.log` |

---

# Monitoring and Health

Navigate to **Moveworks Setup > Core Platform > On-Premise Agents** to see all deployed and reachable agents.

![](https://files.readme.io/1764c11118571e096ed99ba316bb2c6e4649ff16814b329b0f21e22cd3f22728-image.png)

## Agent Health

Agent health reflects the agent's ability to serve requests from the Moveworks platform.

| Status        | Meaning                                                                 |
| ------------- | ----------------------------------------------------------------------- |
| **Healthy**   | Agent successfully serves requests more than 90% of the time            |
| **Unhealthy** | 10 or more out of 100 connection attempts from Moveworks failed         |
| **Unknown**   | No calls have been made to this agent yet — health cannot be determined |

> **Info**
>
> Agent health reflects the ability to serve requests, not the health of the Docker container itself. A running container can show as Unknown if it has not yet received any requests.

## Agent Status

| Status       | Meaning                                                                                                     |
| ------------ | ----------------------------------------------------------------------------------------------------------- |
| **Active**   | Container is running and connected to the Moveworks platform                                                |
| **Inactive** | Agent has stopped or failed to connect. Remains visible for \~30 minutes before being removed from the list |

---

# Credential Rotation

## Rotating the Moveworks Org Access Secret

If the org access secret expires or needs to be rotated:

1. Navigate to **Moveworks Setup > Core Platform > On-Premise Agents**
2. Click **Generate Secret** and save the new secret
3. Reconfigure the agent with the new secret:
   ```shell
   sudo ./setup_agent.sh --configure
   ```
4. When prompted for `access_secret`, enter the new value

> **Warning**
>
> The org access secret expires if not used within 30 days of generation. If the agent shows as Inactive or logs a 401 error, rotate the secret first.

## Rotating the LDAP / AD Service Account Password

When the Active Directory service account password changes, update it in the agent config:

1. Log into the agent VM and navigate to the Moveworks folder
2. Stop the agent:
   ```shell
   sudo ./setup_agent.sh --stop
   ```
3. Open the config file:
   ```shell
   vi /home/moveworks/agent/conf/agent_config.yml
   ```
4. Under `ldap_service_password`, change `encrypted_value` to `value` and replace the old value with the new password:
   ```yaml
   ldap_service_password:
     value: your-new-password
   ```
5. Save and exit (`:wq` in vi)
6. Start the agent:
   ```shell
   sudo ./setup_agent.sh --start
   ```
7. Verify the config — the agent automatically re-encrypts `value` back to `encrypted_value` on start:
   ```shell
   cat /home/moveworks/agent/conf/agent_config.yml
   ```

## Rotating a REST Service Account Password

Follow the same steps as above, locating the relevant `password` field under `rest_configs` in `agent_config.yml`:

```yaml
rest_configs:
  SNOW:
    header_decorators:
    - basic_auth:
        username: admin
        password:
          value: your-new-password
```

Start the agent after saving — it will encrypt the value automatically.

---

## See Also

* [Troubleshooting](/tool-studio/moveworks-agent/moveworks-agent-troubleshooting) — known errors, LDAP and TLS issues, connectivity diagnostics