MAX

Login, sessions and profiles — MAX

Log in to MAX, manage account profiles and sessions, and troubleshoot authentication from your computer.

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

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

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

MethodWhat happensRequirements
token (default)Paste a token issued by an official client, or pipe it inNone
qrA 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 agentA terminal about 70 columns wide, or an agent
qr-chromeweb.max.ru opens in a separate browser window; scan its QR codeChrome, Chromium, Edge or Brave
smsThe same web.max.ru window; choose phone-number login on the pageChrome, Chromium, Edge or Brave

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.

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.

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

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.

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:

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.

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

Check and exit

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:

{ "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?

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:

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

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:

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:

✗ 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:

"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 section.

Storage locations

DataLocation
TokenOS keyring, service max-cli, entry named after the profile
Token without a keyringcredentials.json beside settings, permissions 0600
CI tokenMAX_TOKEN; overrides keyring
Bot tokenOS 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.

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