> 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 Configuration Reference The agent container requires the configuration to be in YAML format in the `/home/moveworks/agent/conf` directory with the file name as `agent_config.yml`. The configuration encompasses various aspects such as Moveworks-specific settings, LDAP and REST client configurations, secrets management, and proxy settings. # Secret Object A secret object is a field in the configuration that is a protected value. All credentials in the configuration are stored as a secret object. There are 3 types of secret objects: 1. **Plaintext/Encrypted Plaintext**: These secrets are stored in the config YAML itself. Once the agent starts, all `value` objects are converted to `encrypted_value` objects for security. ```yaml value: "your-default-secret" # Or after encryption: # encrypted_value: "your-encrypted-secret" ``` 2. **AWS Secrets Manager**: These secrets can be fetched from AWS Secrets Manager. ```yaml aws_entry: secret_name: "my-aws-secret" # Name of the secret in AWS Secrets Manager region: "us-west-2" # AWS region where the secret is stored refresh_time_sec: 3600 # Time interval in seconds to refresh / retrieve the secret ``` 3. **Azure Key Vault**: These secrets can be fetched from Azure Key Vault ```yaml azure_entry: secret_name: "my-azure-secret" # Name of the secret in Azure Key Vault vault: "my-azure-vault" # Name of the Azure Key Vault refresh_time_sec: 3600 # Time interval in seconds to refresh / retrieve the secret ``` \ For worked examples of complete configurations, see [Configuration Examples](/tool-studio/moveworks-agent/moveworks-agent-configuration-guides/configuration-examples). ## Top-Level Fields | Field | Type | Required | Description | | ------------------------- | ------ | -------------- | -------------------------------------------------------------------------------------------------------- | | `bond_version` | string | Yes (auto-set) | Agent configuration version. Set automatically by `setup_agent.sh` — do not edit. | | `moveworks_config` | object | Yes | Authentication and connectivity settings for the Moveworks platform. | | `ldap_config` | object | No | Single-domain LDAP/Active Directory configuration. Use `ldap_forest_config` for multiple domains. | | `ldap_forest_config` | map | No | Multi-domain LDAP configuration, keyed by domain name. Uses the same fields as `ldap_config`. | | `rest_configs` | map | No | REST API client configurations, keyed by service name (e.g. `JIRA`, `SNOW`). | | `secrets_provider_config` | object | No | External secrets manager configuration. Only required when using AWS Secrets Manager or Azure Key Vault. | | `moveworks_proxy_configs` | map | No | Proxy configurations, keyed by proxy name. | ## moveworks_config | Field | Type | Required | Description | Example | | ------------------------- | ------------- | -------- | ----------------------------------------------------------------------------------- | ------------------------------------------- | | `auth_url` | string | Yes | Authentication endpoint URL. | `https://agent.moveworks.com/api/v1/auth` | | `config_url` | string | Yes | Configuration fetch endpoint URL. | `https://agent.moveworks.com/api/v1/config` | | `access_key` | string | Yes | Your organization name (all lowercase). | `your-org-name` | | `moveworks_access_secret` | secret object | Yes | Org access secret. Generate in Moveworks Setup > Core Platform > On-Premise Agents. | — | | `path_to_cert` | string | No | Path to a TLS certificate for connecting to the Moveworks platform. | `/home/moveworks/agent/certs/cert.pem` | ## secrets_provider_config | Field | Type | Required | Description | Example | | --------------------- | ------ | -------- | ------------------------------- | ----------------------------------- | | `aws.default_region` | string | No | Default AWS region for secrets. | `us-west-2` | | `azure.default_vault` | string | No | Default Azure Key Vault URL. | `https://my-vault.vault.azure.net/` | ## ldap_config | Field | Type | Required | Description | Example | | ----------------------- | ------------- | -------- | ----------------------------------------------------------------------------- | ------------------------------------------- | | `enabled` | boolean | No | Whether LDAP is enabled. | `true` | | `host` | string | Yes | LDAP server hostname or IP. Do not include `ldap://` prefix. | `ldap.company.com` | | `port` | integer | Yes | LDAP port. 636 for LDAPS, 389 for LDAP/StartTLS. | `636` | | `domain` | string | No | Domain name without protocol prefix. | `company.com` | | `service_user` | string | Yes | Service account username. Active Directory format: `DOMAIN\username`. | `COMPANY\svc_moveworks` | | `ldap_service_password` | secret object | Yes | Password for the LDAP service account. | — | | `use_ssl` | boolean | No | Use LDAPS (SSL from connection start). Recommended with port 636. | `true` | | `use_start_tls` | boolean | No | Use StartTLS (upgrade to TLS after connecting). Typically used with port 389. | `false` | | `path_to_cert` | string | No | Path to the CA certificate for TLS verification. | `/home/moveworks/agent/certs/ldap_cert.pem` | | `tls_skip_verify` | boolean | No | Skip TLS certificate verification. Do not use in production. | `false` | `ldap_forest_config` uses the same fields as `ldap_config`, with domain names as map keys. ## rest_configs | Field | Type | Required | Description | Example | | ----------------------- | ------- | -------- | -------------------------------------------------------------------------------------------- | ----------------------------------------- | | `service` | string | Yes | Service identifier. Must match the service name configured in Moveworks Setup. | `JIRA` | | `enabled` | boolean | No | Whether this REST config is enabled. | `true` | | `header_decorators` | array | No | Authentication and header configurations. See [Header Decorators](#header-decorators) below. | — | | `body_decorators` | array | No | Request body configurations. See [Body Decorators](#body-decorators) below. | — | | `url_decorators` | array | No | URL/query parameter configurations. See [URL Decorators](#url-decorators) below. | — | | `do_not_use_rest_proxy` | boolean | No | Bypass the configured REST proxy for this client. | `true` | | `ca_cert_path` | string | No | CA certificate path for TLS verification for this service. | `/home/moveworks/agent/certs/ca-cert.pem` | | `tls_skip_verify` | boolean | No | Skip TLS certificate verification. Do not use in production. | `false` | | `max_response_size` | integer | No | Maximum response size in bytes. Default: 10 MB. | `1048576` | | `use_ntlmv2` | boolean | No | Use NTLMv2 authentication. | `false` | ## moveworks_proxy_configs | Field | Type | Required | Description | Example | | ------------ | ------- | -------- | ----------------------------------------------------- | --------------------------- | | `target_url` | string | Yes | URL of the target where forwarded requests should go. | `https://proxy.example.com` | | `port` | integer | Yes | Port the proxy listens on. | `8080` | ## Decorators Decorators attach authentication or fixed values to every request made through a REST client. Multiple decorators can be combined in a single `rest_configs` entry. ### Header Decorators Add to `header_decorators`. Applied to the HTTP headers of every outbound request. | Type | YAML key | Description | | ------------------------- | -------------------------------- | ----------------------------------------------------------- | | Static header | `plain` | Add a fixed key-value header | | File-based | `file` | Load headers from a JSON file at runtime | | Basic Auth | `basic_auth` | HTTP Basic Authentication | | OAuth2 Client Credentials | `oauth2_client_credentials_auth` | Machine-to-machine OAuth2; credentials sent in request body | | OAuth2 Basic Auth | `oauth2_basic_auth` | OAuth2 where credentials are sent as a Basic Auth header | | OAuth2 Refresh Token | `oauth2_refresh_token_auth` | OAuth2 with a long-lived refresh token | | Custom Auth | `custom_auth` | Custom token endpoint for non-standard auth flows | **`plain`** — Fields: `header_key` (string), `header_value` (string). **`file`** — Fields: `file_path` (string). File must be a flat JSON object mapping header names to values. **`basic_auth`** — Fields: `username` (string), `password` (secret object). **OAuth2 types** (`oauth2_client_credentials_auth`, `oauth2_basic_auth`, `oauth2_refresh_token_auth`) share these top-level fields: | Field | Required | Description | | ---------------------- | ------------------ | ---------------------------------------- | | `client_id` | Yes | OAuth2 client identifier | | `client_secret` | Yes | OAuth2 client secret (secret object) | | `client_refresh_token` | Refresh token only | Long-lived refresh token (secret object) | | `scope` | Recommended | Space-separated OAuth2 scopes | | `rest_call_config` | Yes | Token endpoint settings — see below | **`rest_call_config`** (shared by all OAuth2 types): | Field | Default | Description | | -------------------- | --------------------------------------------------- | ----------------------------------------------------------------- | | `url` | — | Token endpoint URL (secret object, required) | | `method` | `POST` | HTTP method for the token request | | `header_key` | `Authorization` | Header name to send the token in | | `header_template` | `Bearer %s` | Format string for the header value | | `refresh_time_sec` | `3600` | How often to refresh the token (seconds) | | `token_body_key` | `access_token` | JSON key to extract the token from the response | | `token_body_pattern` | — | Regex to extract the token when the response is not standard JSON | | `request_body` | — | Custom body for the token request | | `auth_headers` | `{Content-Type: application/x-www-form-urlencoded}` | Headers sent with the token request | **`custom_auth`** uses the same fields as `rest_call_config` directly (no nested object). Use it for non-standard token endpoints that don't follow OAuth2 conventions. For full YAML examples of every header decorator type, see [Header Decorators](/tool-studio/moveworks-agent/moveworks-agent-configuration-guides/configuration-examples#header-decorators) in Configuration Examples. --- ### Body Decorators Add to `body_decorators`. Merge key-value pairs into the request body of every outbound request. | Type | YAML key | Description | | ------------ | -------- | ---------------------------------------------- | | Static value | `plain` | Add a fixed key-value pair to the request body | | File-based | `file` | Load body values from a JSON file at runtime | **`plain`** — Fields: `body_key` (string), `body_value` (string). **`file`** — Fields: `file_path` (string). File must be a flat JSON object mapping field names to values. See [Body Decorators](/tool-studio/moveworks-agent/moveworks-agent-configuration-guides/configuration-examples#body-decorators) in Configuration Examples. --- ### URL Decorators Add to `url_decorators`. Append query parameters to the URL of every outbound request. | Type | YAML key | Description | | ---------------------- | ------------------------ | --------------------------------------------------- | | Static query parameter | `plain_query_parameter` | Append a fixed query parameter to every request URL | | Oracle WebCenter Auth | `oracle_web_centre_auth` | Token-based authentication for Oracle WebCenter | **`plain_query_parameter`** — Fields: `query_key` (string), `query_value` (secret object). **`oracle_web_centre_auth`** — Fields: `username` (string), `password` (secret object), `query_parameter` (object with `query_key`, `query_template`, and `rest_call_config`). See [URL Decorators](/tool-studio/moveworks-agent/moveworks-agent-configuration-guides/configuration-examples#url-decorators) in Configuration Examples.