# App settings files

An app's settings: the optional `.mtr` file beside an app's Cogniscript (`.mtc`) code. The app's inputs come from the parameters of its `main` function, not from this file.

What app settings are for, and how to use them: [Apps](https://docs.maitento.com/concepts/apps.md).

## Where the file goes

`apps/<name>/`: Each sub-folder of `apps/` is one app, named after the folder; the `.mtr` file in it may have any name. A folder holds at most one `.mtr` file.

A resource's name is its file name without `.mtr` (an app's is its folder's name). Use letters, digits, `_`, `-` and `.` (but not `..`), at most 128 characters. Two files of the same kind may not have the same name, even in different sub-folders or with different capitals.

## Properties

Every property is optional.

### `functions.openApi`

Optional. [List of blocks](#each-item-of-functionsopenapi).

Tools the app's code calls with `ExtOpInvoke`. Listing a tool here pins the version it had when the app was deployed; a tool that is not listed is called at its latest version.

### `duration.max`

Optional. Duration, `"hh:mm:ss"`.

The longest a run of the app may take, as `"hh:mm:ss"`. The run is stopped when it is reached.

```hcl
duration.max = "00:05:00"
```

### `credentialStack`

Optional. Text.

The credential stack the app's runs use, by name, when their start doesn't name one, and every interaction and code pipeline they start. Its credentials serve every model call, and Maitento's own keys never do. Leave it out to use the namespace's default stack, then your tenant's.

```hcl
credentialStack = "..."
```

## Each item of `functions.openApi`

A tool made available in one place (to a whole interaction, to one participant, or to an app), with any values and credentials that apply there: `{ ref = @ref("search-handbook") }`. What is set here overrides the tool's own settings.

### `functions.openApi` › `ref`

**Required.** Reference to a tool.

The tool.

```hcl
ref = @ref("search-handbook")
```

### `functions.openApi` › `bindings.path`

Optional. Map of text, one line per entry: `bindings.path:<key> = "value"`.

Fixed values for the connector's path parameters, one line each: `bindings.path:orderId = "A-1001"`.

```hcl
bindings.path:orderId = "A-1001"
```

### `functions.openApi` › `bindings.query`

Optional. Map of text, one line per entry: `bindings.query:<key> = "value"`.

Fixed values for the connector's query parameters, one line each: `bindings.query:units = "metric"`.

```hcl
bindings.query:units = "metric"
```

### `functions.openApi` › `name`

Optional. Text.

The name the model calls the tool by here. The tool's own name when not set.

```hcl
name = "search-handbook"
```

### `functions.openApi` › `bindings.request`

Optional. Map of text, one line per entry: `bindings.request:<key> = "value"`.

Fixed values for fields of the request body, which the model never sees or chooses, one line each: `bindings.request:field = "value"`. Separate the names of a nested field with `/` (`bindings.request:customer/id`). A value is read as the type the request schema gives the field.

```hcl
bindings.request:customer/id = "C-42"
```

### `functions.openApi` › `auth`

Optional. [Block](#the-functionsopenapi--auth-block).

A credential to send with every call made here, instead of the tool's own.

### `functions.openApi` › `guidance`

Optional. Text.

When and how to use the tool here, instead of the tool's own `guidance`. The model reads it.

```hcl
guidance = "Use it when the customer asks about an order."
```

### `functions.openApi` › `terminal`

Optional. `true` or `false`. Default: `false`.

A successful call ends the agent's turn: the result is recorded, and the model is not asked to continue. Use it for a "finish" tool that is meant to be the last thing an agent does in a turn.

```hcl
terminal = true
```

## The `functions.openApi` › `auth` block

A credential sent with every call of a tool: `auth = { header = "X-Api-Key" secret = @ref("orders-api-key") }`. The tool's connector needs `auth = "Header"`.

### `auth` › `header`

**Required.** Text.

The HTTP header the secret's value is sent in. For `Authorization`, a value without a space is sent as `Bearer <value>`.

```hcl
header = "X-Api-Key"
```

### `auth` › `secret`

**Required.** Reference to a secret.

The secret whose value is sent. Create the secret before you deploy.

Secrets are not part of a project: create them in the portal, with the SDK or with `mt secret-create` before you deploy.

```hcl
secret = @ref("orders-api-key")
```

## A complete example

From the [16-apps](https://github.com/maitento/maitento/tree/main/examples/16-apps) example project:

```hcl title="apps/taglines/taglines.mtr"
// Optional settings for the app. Stop it if it runs for more than five minutes.
duration.max = "00:05:00"
```