# Configuration (/en/docs/max/configuration)

Keep settings you would otherwise repeat on every command. This guide explains their locations and priority so you can change a value and check which setting takes effect.

[Change and check settings](/llms.mdx/docs/configuration/content.md)

Use this page when you repeatedly type the same option or want `max` to behave differently for one account. You will learn where the settings file lives, which basic settings to change, how to change one value and how to check the effective value. No file is needed to start: every setting has a built-in default.

Terms used below:

- **Configuration file** (`config.json`) — the text file storing your saved choices.
- **Profile** — named settings for one MAX account or bot, such as `work`. Put its name before the command: `max work chats list`. See [profiles and bots](/llms.mdx/docs/max/profiles/content.md).
- **Option** (flag) — a word added to a command, such as `--limit 5`. It affects only that run.
- **Environment variable** — a named value passed to `max` by a terminal or agent process, such as `MAX_PROFILE=work`.
- **Default** — the value `max` uses when you specify no other value.

## What you can configure [#what-you-can-configure]

These settings are changed most often. The [configuration reference](/llms.mdx/docs/max/configuration-reference/content.md#%D1%84%D0%B0%D0%B9%D0%BB) gives each setting's exact type and all override methods.

| Setting | Purpose | Built-in default |
| --- | --- | --- |
| `limit` | Rows displayed without `--limit` | `20` |
| `sends_per_hour` | Messages a profile may send per hour; stops sending loops | `30`; bots have no limit until set in `bot` |
| `requests_per_minute` | Request rate after an initial short burst; `0` disables pacing ([limits and waits](/llms.mdx/docs/max/limits/content.md)) | `20` |
| `permissions` | Read, ask before changes or act without asking ([permissions](/llms.mdx/docs/max/permissions/content.md)) | All allowed except deletion and some other irreversible changes ask first; auto-reply sending is disabled |
| `record` | Save successful runs too, not only failed ones ([diagnostics](/llms.mdx/docs/max/diagnostics/content.md)) | `true` |
| `record_input` | Whether a run record keeps the command line as you typed it; secrets are always hidden ([diagnostics](/llms.mdx/docs/max/diagnostics/content.md#%D1%87%D1%82%D0%BE-%D0%B2%D1%8B-%D0%BD%D0%B0%D0%B1%D1%80%D0%B0%D0%BB%D0%B8)) | `true` |
| `keep_runs_for_days` | Days to retain run records | `30` |
| `color` | Table colours | Based on terminal |
| `sender_colors` | Different colour for each message author | `false` |
| `timeout_ms` | Milliseconds to wait for **one** MAX response; use `--timeout` for the whole command | Transport-dependent |
| `serve` | Start background `max personal serve` when a command needs MAX ([one shared login](/llms.mdx/docs/max/limits/content.md#%D0%BE%D0%B4%D0%B8%D0%BD-%D0%B2%D1%85%D0%BE%D0%B4-%D0%BD%D0%B0-%D0%B2%D1%81%D1%91)) | `true` |
| `transcribe_model` | Speech-recognition model for voice messages | `gigaam-v3` |
| `update_check` | Report new `max` versions once a day | `true` |

There is no place for secrets in this file: no token, phone number or chat id. Tokens use the system keyring or, if unavailable, a file only you can read ([token storage](/llms.mdx/docs/max/security/content.md#%D0%B3%D0%B4%D0%B5-%D0%B6%D0%B8%D0%B2%D1%91%D1%82-%D1%82%D0%BE%D0%BA%D0%B5%D0%BD)).

## Example configuration file [#example-configuration-file]

The first command that reads the settings creates an initial file; `max personal doctor` does not create it. Here it is with one profile added:

```json
{
  "defaults": { "limit": 20, "keep_runs_for_days": 30, "sends_per_hour": 30, "update_check": true, "skill_hint": true },
  "profiles": {
    "work": { "limit": 50 }
  }
}
```

- `defaults` applies to all profiles.
- `profiles.work` applies only to `work` and overrides `defaults`.

Thus `max work chats list` shows 50 rows, while `max personal chats list` shows 20. Add `--limit 5` for five rows in one command. Remove the profile's `limit` to use `defaults` again.

<details> <summary>Full example with all sections</summary>

```json
{
  "defaults": {
    "limit": 20,
    "keep_runs_for_days": 14,
    "sends_per_hour": 30,
    "requests_per_minute": 20,
    "update_check": true,
    "skill_hint": true,
    "transcribe_model": "gigaam-v3"
  },
  "profiles": {
    "personal": {
      "limit": 50,
      "color": true,
      "sender_colors": true,
      "record": true
    },
    "work": {
      "permissions": { "messages": "readonly", "messages.send": "allow" },
      "sends_per_hour": 10,
      "serve": false
    }
  },
  "personal": {
    "defaults": { "search_catch_up": true }
  },
  "bot": {
    "defaults": { "permissions": { "bot": "readonly", "bot.messages.send": "allow" } },
    "profiles": {
      "shop": { "sends_per_hour": 200, "read_other_bots": false }
    }
  }
}
```

What each part does:

- `defaults`: every profile receives these values unless it overrides them. `update_check`, `skill_hint` and `transcribe_model` are allowed only here because the program and speech-recognition downloads are shared by all profiles.
- `profiles.personal`: more rows, colours and recording every run, only for `personal`.
- `profiles.work`: reading and sending messages are allowed; other message changes are denied. At most 10 sends per hour. No background server starts: each command connects to MAX itself.
- `personal.defaults`: applies only to personal-account commands, never `max … bot`. Here `messages sync` also prepares downloaded chats for search.
- `bot.defaults`: applies only to bot commands (`max shop bot …`). Bots can read and send, and do nothing else.
- `bot.profiles.shop`: `shop` can send 200 messages per hour and cannot read other bots' saved data on this computer. `read_other_bots` is allowed only in `bot`; `serve`, `sender_colors` are not accepted there.

</details>

## File location [#file-location]

| System | Path |
|---|---|
| Linux and macOS | `~/.config/max-cli/config.json` |
| Windows | `%APPDATA%\max-cli\Config\config.json` |

`max config show` prints this computer's actual path and each setting with its value, where the value came from, the built-in value, and what the setting does. In PowerShell, use `max.cmd` instead of `max`. An existing file is never replaced with the initial file.

`max config migrate` adds to `defaults` every setting missing from the file, with its built-in value, so every setting is visible and editable right in the file. Your values, their order, and unknown keys stay as they are. Any write by `max` to the file, such as `config set`, does the same; `config unset` does not write the removed setting back.

## Three ways to set a value [#three-ways-to-set-a-value]

- **File:** the value persists for future commands. `max personal config set limit 50` saves it.
- **Environment variable:** applies to one terminal or agent process. For example, `MAX_PROFILE` selects a profile and `MAX_TIMEOUT` limits command duration. Not every setting has a variable.
- **Option:** `--limit 5` affects only one command.

## Which value takes precedence? [#which-value-takes-precedence]

Options override environment variables, followed by the profile's file value, file `defaults`, then built-in defaults. Each setting supports only certain methods; the [configuration reference](/llms.mdx/docs/max/configuration-reference/content.md#%D0%BA%D0%B0%D0%BA%D0%BE%D0%B5-%D0%B7%D0%BD%D0%B0%D1%87%D0%B5%D0%BD%D0%B8%D0%B5-%D0%BF%D0%BE%D0%B1%D0%B5%D0%B6%D0%B4%D0%B0%D0%B5%D1%82) lists them.

## Change a value [#change-a-value]

Edit the file with any text editor or let `max` do it. `config set` validates before writing, so it never saves a file the next command would reject.

```sh
max personal config set limit 50                 # профилю, с которым вы работаете
max work config set limit 50            # профилю work
max config set sends_per_hour 10 --defaults   # всем профилям
max personal config unset limit                  # вернуть значение по умолчанию
max config show                         # проверить, что действует и откуда взялось каждое значение
```

A misspelled setting is an error rather than a silent default: every command stops and names the invalid key ([file typos](/llms.mdx/docs/max/configuration-reference/content.md#%D0%BE%D0%BF%D0%B5%D1%87%D0%B0%D1%82%D0%BA%D0%B0--%D1%8D%D1%82%D0%BE-%D0%BE%D1%88%D0%B8%D0%B1%D0%BA%D0%B0-%D0%B0-%D0%BD%D0%B5-%D1%83%D0%BC%D0%BE%D0%BB%D1%87%D0%B0%D0%BD%D0%B8%D0%B5)).

## Profiles and bots [#profiles-and-bots]

A profile stores settings for one account or bot. Put its name before the command, such as `max work config show`. To act as a bot, add `bot` after the name. [Profiles and bots](/llms.mdx/docs/max/profiles/content.md) explains creating profiles and switching between them.

## Next steps [#next-steps]

- [Permissions](/llms.mdx/docs/max/permissions/content.md): choose what a profile and its agent may do.
- [Configuration reference](/llms.mdx/docs/max/configuration-reference/content.md): every setting, type, allowed scope and environment variable.
- [External models](/llms.mdx/docs/max/external-models/content.md): providers, keys and AI configuration for reading image text (OCR).
