# Define runtime parameters

> Define runtime parameters - Add runtime parameters to a custom app, making the application code
> easier to reuse.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-05-06T18:17:10.021257+00:00` (UTC).

## Primary page

- [Define runtime parameters](https://docs.datarobot.com/en/docs/wb-apps/custom-apps/nxt-runtime-parameter-custom-app.html): Full documentation for this topic (HTML).

## Sections on this page

- [Runtime parameter definitions](https://docs.datarobot.com/en/docs/wb-apps/custom-apps/nxt-runtime-parameter-custom-app.html#runtime-parameter-definitions): In-page section heading.

## Related documentation

- [Applications](https://docs.datarobot.com/en/docs/wb-apps/index.html): Linked from this page.
- [Applications](https://docs.datarobot.com/en/docs/wb-apps/custom-apps/index.html): Linked from this page.
- [Manage application sources](https://docs.datarobot.com/en/docs/wb-apps/custom-apps/manage-app-source.html#runtime-parameters): Linked from this page.
- [API reference documentation for credentials](https://docs.datarobot.com/en/docs/api/reference/public-api/credentials.html#schemacredentialsbody): Linked from this page.

## Documentation content

Define environment variables to supply different values to application code at runtime by including them as runtime parameters, making your application easier to reuse. Define runtime parameters in code or through the UI:

- Code: Provide ametadata.yamlfile in the application source. Define this file when creating or editing an application source in theApplicationsworkshop, or use the template available in theApplicationsworkshop through an application'sFiles >Createdropdown. The YAML structure is definedon this page.
- UI: Define runtime parameters in theRuntime parameterssection of the application source in theApplicationsworkshop. For more information, see theManage application sourcesdocumentation.

Runtime parameters are injected into containers as environment variables (accessible through `os.getenv`). Parameters [created via theApplicationsworkshop UI](https://docs.datarobot.com/en/docs/wb-apps/custom-apps/manage-app-source.html#runtime-parameters) persist and merge when you upload new code versions, ensuring a seamless development flow.

**Runtime parameter considerations**

The system uses a blocklist of reserved patterns (e.g., `DRUM_*`, `MLOPS_*`, `KUBERNETES_*`), managed in the dynamic configuration. Matching supports the `*` wildcard (not full regular expression syntax). Reserved names aren't blocked entirely: if a runtime parameter uses a reserved name, the UI displays a warning. How the variable is exposed depends on the context:

- Custom models: Only in prefixed ( MLOPS_RUNTIME_PARAM_* ) and JSONified format—not as a raw (unprefixed) environment variable, to prevent system conflicts.
- Custom apps: Prefixed, but values are not packed into a JSON payload (except for credentials).
- Custom jobs: No prefix and no JSON payload (except for credential types); the variable is available as a raw environment variable.

For credential-type runtime parameters, the system automatically unpacks JSON fields into separate environment variables rather than a single string. For example, a credential named `MAIN_AWS_CREDENTIAL` with the following JSON structure:

```
{"awsAccessKeyId": "<your-key-id>", "awsSecretAccessKey": "<your-access-key>"}
```

is unpacked into the following environment variables, combining the parameter name + JSON key, in uppercase:

```
MAIN_AWS_CREDENTIAL_AWS_ACCESS_KEY_ID="<your-key-id>"
MAIN_AWS_CREDENTIAL_AWS_SECRET_ACCESS_KEY="<your-access-key>"
```

For single-field credential types (for example, `api_token`, `bearer`, or `gcp`), the injected environment variable uses the bare runtime parameter name ( `MY_CRED`), not the parameter name plus the credential field name (for example, not `MY_CRED_API_TOKEN`).Multi-field credential types (for example, `basic` or `s3`) keep the existing suffixed behavior: one variable per field, named `{PARAMETER_NAME}_{FIELD_NAME}` in uppercase snake case (for example, `MY_CRED_USERNAME` and `MY_CRED_PASSWORD`, or the AWS keys in the example above). JSON-encoded runtime parameter variables (for example, `MLOPS_RUNTIME_PARAMETERS_OPEN_AI_API`) are unchanged; only the flat variable for a single-field secret uses the bare parameter name.

> [!TIP] Access runtime parameters in containers
> For programmatic access to runtime parameters in containers, use `DataRobotAppFrameworkBaseSettings` as documented in the SDK API reference.

## Runtime parameter definitions

To define runtime parameters, you can add the following `runtimeParameterDefinitions` in `metadata.yaml`:

| Key | Description |
| --- | --- |
| fieldName | Define the name of the runtime parameter. |
| type | Define the data type the runtime parameter contains: string, boolean, numeric, credential, deployment, modelPackage. |
| defaultValue | (Optional) Set the default string value for the runtime parameter (the credential type doesn't support default values). If you define a runtime parameter without specifying a defaultValue, the default value is None. |
| minValue | (Optional) For numeric runtime parameters, set the minimum numeric value allowed in the runtime parameter. |
| maxValue | (Optional) For numeric runtime parameters, set the maximum numeric value allowed in the runtime parameter. |
| credentialType | (Optional) For credential runtime parameters, set the type of credentials the parameter must contain. |
| allowEmpty | (Optional) Set the empty field policy for the runtime parameter.True: (Default) Allows an empty runtime parameter.False: Enforces providing a value for the runtime parameter before deployment. |
| description | (Optional) Provide a description of the purpose or contents of the runtime parameter. |

```
# Example: metadata.yaml
name: runtime-parameter-example

runtimeParameterDefinitions:
- fieldName: my_first_runtime_parameter
  type: string
  description: My first runtime parameter.

- fieldName: runtime_parameter_with_default_value
  type: string
  defaultValue: Default
  description: A string-type runtime parameter with a default value.

- fieldName: runtime_parameter_boolean
  type: boolean
  defaultValue: true
  description: A boolean-type runtime parameter with a default value of true.

- fieldName: runtime_parameter_numeric
  type: numeric
  defaultValue: 0
  minValue: -100
  maxValue: 100
  description: A boolean-type runtime parameter with a default value of 0, a minimum value of -100, and a maximum value of 100.

- fieldName: runtime_parameter_for_credentials
  type: credential
  allowEmpty: false
  description: A runtime parameter containing a dictionary of credentials.
```

The `credential` runtime parameter type supports any `credentialType` value available in the DataRobot REST API. The credential information included depends on the `credentialType`, as shown in the examples below:

> [!NOTE] Note
> For more information on the supported credential types, see the [API reference documentation for credentials](https://docs.datarobot.com/en/docs/api/reference/public-api/credentials.html#schemacredentialsbody).

| Credential Type | Example |
| --- | --- |
| basic | basic: credentialType: basic description: string name: string password: string user: string |
| azure | azure: credentialType: azure description: string name: string azureConnectionString: string |
| gcp | gcp: credentialType: gcp description: string name: string gcpKey: string |
| s3 | s3: credentialType: s3 description: string name: string awsAccessKeyId: string awsSecretAccessKey: string awsSessionToken: string |
| api_token | api_token: credentialType: api_token apiToken: string name: string |