# Login, sessions and profiles (/en/docs/max/sessions)

Connect the tool to your messenger account so your agent can read the chats you choose and help with replies. This guide explains login, checking the connection and managing or ending a session. Login adds an authorised device; it does not download all your chat history.

Use this page when connecting `max` to a MAX account for the first time, adding a second account or recovering from “no session”. You will learn to log in, check which account is connected, log out, and locate the saved data that keeps the login available.

Terms used below:

- **Session** — this computer's `max` login to your MAX account, consisting of a token and device identity. MAX lists it as another device in the app.
- **Token** — the credential MAX issues at login. It can read your chats; treat it as a password. `max` keeps it in the keyring.
- **Device identity** — how `max` identifies itself to MAX, consistently across commands. It is saved beside other state files.
- **Keyring** — the operating system's password storage: Keychain on macOS, Secret Service (GNOME Keyring, KWallet) on Linux, Credential Manager on Windows.
- **Profile** — a named login with its own token, state and settings. The name is given in every command (`max personal …`) or by `MAX_PROFILE`; `max` never picks a profile by itself. You need another profile for another account or separate restrictions ([profiles](#профили)).

Do not confuse `max personal session` and `max personal account sessions`. `max personal session` — login of `max` itself; `max personal account sessions` lists all other devices and applications signed into your account.

## First run [#first-run]

`max personal setup` checks local directories, guides you through QR login, checks your account and up to five chats, and installs the agent skill. Agent choices: `codex`, `cursor`, `claude`, `gemini`, `all`, `none`. Without a parameter, an interactive terminal asks you; machine mode skips skill installation. `max skill show` is available before login.

Allow about five minutes. History downloads separately after you choose a chat and volume; setup does not start a background service. Repeating setup checks the existing session. `--method token|qr|qr-chrome|sms` selects a new login method; default `qr`. `qr-chrome` and `sms` require a person at the local terminal. Without a terminal, `qr` prints the QR code as text: the agent pastes it into the chat and the owner scans it from the screen (see [Login through an agent](#вход-через-агента)). Do not pass a token as an argument. Repeat interrupted setup. For an expired token, explicitly run `max personal session start qr`; if the keyring is unavailable, follow the environment repair guidance first.

## Log in [#log-in]

`max personal session start <способ>` supports four login methods. Whichever method you use, the token is saved to the keyring only after MAX accepts it.

| Method | What happens | Requirements |
|---|---|---|
| `token` (default) | Paste a token issued by an official client, or pipe it in | None |
| `qr` | A QR code appears directly in the terminal; scan it with the MAX app. In a narrow terminal the code is not drawn: widen the window and run it again. Without a terminal the code is printed as text for an agent | A terminal about 70 columns wide, or an agent |
| `qr-chrome` | web.max.ru opens in a separate browser window; scan its QR code | Chrome, Chromium, Edge or Brave |
| `sms` | The same web.max.ru window; choose phone-number login on the page | Chrome, Chromium, Edge or Brave |

### Login through an agent [#login-through-an-agent]

Without a terminal (an agent runs the command through its shell tool), `max <профиль> session start qr`
prints the QR code on stderr as plain text: `█▀▄` characters, no colour, with the light modules drawn, so on a
dark theme the code reads as black on white. The agent:

1. runs the command in the background — it waits up to 2 minutes for the scan, and a shell tool shows nothing
   until the command ends;
2. reads its output and pastes the QR block into the chat as a code block, exactly as printed;
3. waits for the command to finish: the login result arrives on stdout.

With `--json` each code is also one JSON line on stderr: `{"event":"qr","qr":{"text":…,"expires_at":…,"scan":…}}`.
MAX issues one code per run; when it expires, run the command again. The MAX cloud password cannot be entered this
way: it is asked for only in a terminal. Login is not available through MCP (`session` is not published to MCP, and
login does not go through `serve`): an agent with only MCP has to ask the owner to run the command, or use a shell.

```sh
max personal session start qr
```

1. Keep the QR code visible on your computer, in the terminal or browser window opened by the command.
2. Open MAX on your phone and select the account you want to connect.
3. Go to **Settings → Devices** and open its QR login scanner. Labels can vary by app version.
4. Scan the computer’s QR code using the scanner inside MAX and confirm the connection if asked.
5. If MAX asks for an additional account password, enter it at the terminal prompt; input is hidden.
6. Wait for the command to finish successfully, then run `max personal account show` to verify the account and `max personal chats list --limit 5` to read a few chats.

[Official MAX login instructions](https://help.max.ru/help/account/dostup_k_prophilyu/kak_voiti_v_prophil_max_esli_on_uzhe_est).

**`qr-chrome` and `sms` are the most cautious methods.** web.max.ru handles login in a real browser, so MAX sees its own web client. The browser uses a separate temporary profile, not yours. Once web.max.ru is logged in, the window closes and the profile is deleted, including when you press Ctrl-C. Closing the window does not end the session; it is like closing a tab. The browser is detected automatically; set `MAX_BROWSER` to use another. Snap-packaged browsers are unsupported because they use their own `/tmp` directory.

**`qr` requests a MAX code over `max`'s own connection**, identifying as a web client. It works without a browser, but is not the actual web client.

**login via SMS - only through the browser.** When SMS asks for a `max` connection, MAX requires a captcha, and it can only be completed on the page.

After any of these three methods, a new device appears in the MAX app's session list. If your account has a cloud password, `qr` prompts for it without showing what you type, up to three times. After that, you must scan the code again.

All three require a person at the terminal; otherwise they return code 2. An AI agent without a terminal can use `token`. A program that shows the questions in its own window, such as WireCat Desktop, runs `max personal session start qr --json --answer-stdin`: the cloud password is asked as a `needs` line on stderr, and the answer is one line on stdin. While `MAX_TOKEN` is set, these three methods also refuse: it overrides the keyring and would hide the new session.

### Importing a token manually [#importing-a-token-manually]

`max personal session start` without a method **imports** a token already issued by an official client, such as `web.max.ru`, and stores it in the keyring. This also works when login is blocked by a CAPTCHA or an unusual second factor.

```sh
max personal session start
MAX token: ▏          # ввод не отображается
```

**The token is not accepted as a command argument.** Arguments are visible in `ps` to any process on the machine and remain in shell history. Instead, the terminal prompts without echoing input, or the command reads from a pipe when there is no terminal:

```sh
pass show max/token | max personal session start
```

For CI and one-off runs, use the environment variable. It **takes precedence over the keyring**: when `MAX_TOKEN` is set, it is used without writing anything to the keyring. The background `max personal serve` process does not start with this variable; the command connects to MAX itself.

```sh
MAX_TOKEN="$(cat /path/to/token)" max personal chats list --json
```

## Check and exit [#check-and-exit]

```sh
max personal account show             # под кем выполнен вход: id, имя, последние четыре цифры телефона
max account list             # все профили на этом компьютере и аккаунт каждого
max personal account sessions list    # все устройства и приложения, вошедшие в аккаунт; ничего не завершает
max personal session end              # выйти из MAX и забыть токен на этой машине
```

`session end` first ends the session on the MAX server, then erases the token on this computer. If `max serve` is running for the profile, started manually or by a service, `session end` refuses (exit code 2): run `max personal server stop` first. The response reports the outcome:

```json
{ "item": { "profile": "personal", "forgotten": true, "revoked_on_server": true }, "meta": { … } }
```

To forget a profile completely, use `max personal account remove --keep-data` or `--delete-data`. It also ends the session on the MAX server first. Then it erases the token, the profile files and everything the shared layer keeps for the profile. `--keep-data` keeps the messages in the local store, and search still finds them. `--delete-data` deletes them too. The bot token (`bot:personal`) stays.

**If you signed in with a token from a web.max.ru tab, they share one session:** `session end` also signs that tab out of MAX.

If MAX does not respond, the token is kept so you can retry the command. A token MAX no longer accepts is erased immediately: there is no remaining session to end.

A run with moved folders (`MAX_CONFIG_DIR` and the related variables, a different `HOME` or an XDG folder) uses the owner's sign-in but does not end it: there, `session end` erases nothing, does not sign out of MAX, and answers `"kept": "owners-sign-in"`. A sign-in made in such a run itself is ended by `session end` as usual.

## How long does a session last? [#how-long-does-a-session-last]

MAX does not report a fixed token expiration time, so the CLI cannot promise a number of days. Closing the web.max.ru tab does not end the authorization. If MAX rejects the saved token, reconnect by QR:

```sh
max personal session start qr
```

For a work profile, use `max work session start qr`. Then run `max personal account show` (or `max work account show`) to verify the account. The bare `max personal session start` command imports an existing token rather than displaying a QR code. `max personal doctor` shows the login count for the profile.

## Profiles [#profiles]

Each profile keeps its own token and state; the shared local archive identifies the account for each message. Name a profile as the **first word**, rather than a flag:

```sh
max personal chats list     # профиль personal
max work chats list         # профиль work
export MAX_PROFILE=personal # или на всю сессию оболочки
```

Rule: **The first word is profile unless it matches the name command.** Therefore a profile cannot be named `chats`, `runs` or `session` - `max personal session start` and `max personal setup` reject such a name. Otherwise, `max personal chats` would silently mean “chats profile without command”. The name consists of Latin letters, numbers, periods, hyphens and underscores and begins with a letter or number.

Order, first match wins: first word, `MAX_PROFILE`. If none of these is set, a command that needs an account exits with code `2` and lists the profiles on this computer — even when there is only one:

```text
✗ name a profile: `max <profile> …` — profiles here: personal (or set MAX_PROFILE)
```

On a computer with no profiles, the message says how to create the first one: `max personal setup`. Without a profile, only commands that do not need an account work: `--help`, `--version`, `commands`, `skill show`, `account list`, `config show`.

If the first word is not a command and no command follows it, the program explains what happened instead of silently displaying help:

```text
"nonsense" is not a command, so it was read as a profile name — and no command followed it.
Run `max --help` for the commands, or `max nonsense account show` if "nonsense" is your profile.
```

**`MAX_PROFILE_LOCK` assigns the process to one profile.** Specify it where the agent is running, and the first word or `MAX_PROFILE` with the name of another profile will be rejected (return code `5`). Without it, the agent could choose a profile with fewer restrictions.

Why each profile is needed and how the profile works with the bot - in the [profiles and bots](/llms.mdx/docs/max/profiles/content.md) section.

## Storage locations [#storage-locations]

| Data | Location |
| --- | --- |
| Token | OS keyring, service `max-cli`, entry named after the profile |
| Token without a keyring | `credentials.json` beside settings, permissions `0600` |
| CI token | `MAX_TOKEN`; overrides keyring |
| Bot token | OS keyring, service `max-cli`, entry `bot:<профиль>`; or `MAX_BOT_TOKEN` |
| Chats observed by bots | `~/.local/share/max-cli/bots/` |
| Device, login count, `viewerId` | `~/.local/share/max-cli/profiles/<профиль>.json`, permissions `0600` |
| Settings | `~/.config/max-cli/config.json` |

Directories for macOS and Windows are listed in the section [where everything goes](/llms.mdx/docs/max/installation/content.md#%D0%BA%D1%83%D0%B4%D0%B0-%D0%B2%D1%81%D1%91-%D0%BB%D0%BE%D0%B6%D0%B8%D1%82%D1%81%D1%8F).

**The device identity is saved on the first read**, before it is used. A client that presents itself to MAX as a new device on every command does not behave like a real client; server-side sessions are tied to that identity.

On a machine without a keyring (a typical container), recording fails - then the token is placed in the file `credentials.json` next to the settings, with the rights `0600`, and command says this in one line on stderr. In CI, it is more correct not to rely on either one or the other and pass `MAX_TOKEN`.

> ⚠ `MAX_CONFIG_DIR`, `MAX_STATE_DIR` and `MAX_CACHE_DIR` also change the keyring service name. A session saved with these variables is **not visible** to a command run without them, and vice versa. Set them consistently or leave them unset everywhere.

## Next steps [#next-steps]

- [Read the first chats](/llms.mdx/docs/max/usage/content.md)
- [Settings and the order in which they are applied](/llms.mdx/docs/max/configuration/content.md)
- [What gets on the disk and what never gets](/llms.mdx/docs/max/security/content.md)
