[Bug] mmx fails with misleading "No credentials found" when invoked from a subprocess whose os.homedir() differs from the credential owner's profile

[LegendaryLionMan]

Summary

When mmx is invoked from a non-interactive subprocess whose os.homedir() resolves to a different user's profile than the one where ~/.mmx/config.json lives, mmx quota show (and any other mmx subcommand) fails with exit code 3 — AUTH error, even when the user's credentials are perfectly valid and accessible from their actual user shell.

The error message's remediation hint is misleading: it tells the user to "Log in: mmx auth login" or "Pass directly: --api-key sk-xxxxx", when the actual fix is a single undocumented environment variable (MMX_CONFIG_DIR).

Environment

• mmx 1.0.16 (latest, published 2026-06-01)
• Windows 11, NTFS
• Reproducible on Linux/macOS too (anywhere a service runs under a different user)
• Triggering scenario: an AI agent (Hermes/MiniMax, in our case) spawning mmx from a Python sandbox that runs as NT AUTHORITY\SYSTEM. The user lion_ has valid credentials at C:\Users\lion_\.mmx\config.json, but os.homedir() from the subprocess returns C:\WINDOWS\system32\config\systemprofile because the subprocess inherits SYSTEM's environment.

Reproduction

# Step 1: as user 'lion_', log in once:
mmx auth login --api-key sk-xxxxx
# Confirm working:
mmx quota show --output json   # OK

# Step 2: from a SYSTEM-context subprocess (or any subprocess whose
# os.homedir() resolves to a different profile):
import os, subprocess
# Do NOT set USERPROFILE/MMX_CONFIG_DIR — default behavior:
r = subprocess.run(["mmx", "quota", "show", "--output", "json"],
                   capture_output=True, text=True)
print(r.returncode)   # 3
print(r.stderr)       # {"error":{"code":3,"message":"No credentials found.", ...}}

Actual output (verified 2026-06-30)

$ mmx quota show --output json
{
  "error": {
    "code": 3,
    "message": "No credentials found.",
    "hint": "Log in:        mmx auth login
Pass directly:  --api-key sk-xxxxx"
  }
}

exit code 3.

Root cause

Traced via mmx.mjs (and upstream src/config/paths.ts:7):

export function getConfigDir(): string {
  if (process.env.MMX_CONFIG_DIR) return process.env.MMX_CONFIG_DIR;
  return join(homedir(), CONFIG_DIR_NAME);
}

mmx checks MMX_CONFIG_DIR first, then falls back to os.homedir()/.mmx/. In a SYSTEM-context subprocess, neither is correct — MMX_CONFIG_DIR isn't set, and homedir() returns SYSTEM's profile which has no credentials.

The "No credentials found" error is correct (there genuinely are no credentials at the path mmx looks at), but the hint string (src/auth/credentials.ts-adjacent code) only mentions two options:

1. mmx auth login (interactive — does not work in a non-TTY subprocess)
2. --api-key sk-xxxxx (per-call — works, but doesn't address the underlying config-location issue)

Neither mentions MMX_CONFIG_DIR, even though mmx DOES support it. So a user hitting this case has to grep the source code to discover the fix.

Expected behavior

The error hint should mention MMX_CONFIG_DIR as a remediation, since mmx already supports it. Suggested error hint:

No credentials found.

Remediation:
  1. Run interactively:  mmx auth login
  2. Per-call flag:       --api-key sk-xxxxx
  3. Env var (any of):   MINIMAX_API_KEY=sk-xxxxx
                         MMX_CONFIG_DIR=/path/to/.mmx
  4. Verify path:        ls $(node -e 'console.log(require("os").homedir())')/.mmx/config.json

Documentation gap

The README advertises mmx as:

Built for AI agents. Generate text, images, video, speech, and music from any agent or terminal.

Useful for CI/CD (mmx auth login --api-key sk-xxxxx), or pass per-command via --api-key.

But the README does not document MMX_CONFIG_DIR as an env var. The only env vars documented are: MINIMAX_API_KEY, MINIMAX_BASE_URL, MINIMAX_REGION, MINIMAX_OUTPUT, MINIMAX_TIMEOUT, MINIMAX_VERBOSE (see README §"Auth" and §"Environment").

MMX_CONFIG_DIR is silently functional but invisible to users — they only discover it by reading src/config/paths.ts.

Suggested fix

Two options, both low-risk:

Option A (minimal): Add MMX_CONFIG_DIR to the README's env-var list under "Auth" and update the "No credentials found" error hint to mention it.

Option B (better DX): When mmx runs in non-interactive mode and credentials aren't found at the expected location, ALSO check the calling user's ~/.mmx/ (the one whoami reports, or the one derived from the parent process tree if possible). If found elsewhere, log a console.warn saying "credentials found at but CLI is looking at ; set MMX_CONFIG_DIR to use the found location".

Related

• Issue Auth docs mention ~/.mmx/credentials.json, but authenticated CLI works without that file #80 (~/.mmx/credentials.json vs ~/.mmx/config.json doc mismatch) — same class of bug (docs/code divergence around auth)
• Issue mmx music cover: 4 CLI bugs vs API behavior (model whitelist, error code overloading, missing flags, missing docs) #182 (CLI flag/docs mismatches in mmx music cover) — same maintainer-feedback signal that docs and code drift independently in mmx
• This issue was discovered while investigating a Hermes-side mmx_quota_show failure that had been misdiagnosed as a mmx 1.0.16 ncrypto CSPRNG crash. The actual root cause was the missing env-var wiring on the Hermes plugin side, but the missing hint on the mmx side made the diagnostic cost much higher than it needed to be.