Hermes Agent Provider: MiniMax M3 (Direct)

Quick decision

• Provider: minimax (direct, not via an aggregator)
• Model: MiniMax-M3
• Env var: MINIMAX_API_KEY
• Who it suits: anyone who already has a MiniMax Token Plan or pay-as-you-go key and wants the cheapest, lowest-latency path to M3 from Hermes.

Jump to setup: Sign up and connect MiniMax to Hermes Agent.

Last verified: July 31, 2026. Re-check the Hermes provider docs and the MiniMax Hermes guide before you sign in.

What this guide covers

This is a short, setup-only guide for the direct MiniMax provider path inside Hermes Agent. It pairs with the longer MiniMax Token Plan: Plans, Limits, and Hermes Agent Setup guide, which explains the subscription tiers, quotas, and Hermes implementation in detail.

If you are choosing a MiniMax tier, start with the Token Plan guide. If you already have a key and only need the Hermes wiring, stay here.

Before you set up Hermes Agent

You need:

• a macOS or Linux terminal, or Windows using WSL2
• a MiniMax account and an API key
• a current Hermes Agent installation

Direct links:

• Create or sign in to your MiniMax account
• Get a Token Plan Subscription Key or pay-as-you-go API key
• MiniMax’s Hermes Agent integration page
• Hermes Agent provider documentation

Short setup map

1. Confirm your MiniMax key type. Token Plan uses a dedicated Subscription Key; standard pay-as-you-go uses an API key. Both work with MINIMAX_API_KEY.
2. Run hermes model and choose MiniMax (global endpoint).
3. Select MiniMax-M3 and run the smoke test below.
4. Confirm the key file exists with mode 600; do not print its contents.

Install Hermes Agent

If Hermes is not installed, use the current installer:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Then check the installation:

hermes doctor

Review scripts downloaded with curl | bash before running them if that is your security policy. The current Hermes installation guide is authoritative; check it when you install. The MiniMax integration page may still link to the upstream GitHub copy of the same installer.

Configure MiniMax in Hermes

The current supported route is the interactive model selector:

hermes model

In the prompts:

1. Choose MiniMax (global endpoint).
2. Paste the MiniMax API key when asked.
3. Choose MiniMax-M3.
4. Save the selection and exit the wizard.

Hermes’ native provider ID is minimax and its credential variable is MINIMAX_API_KEY. The wizard stores provider configuration for you; you do not need to invent a custom endpoint. Hermes places persistent API keys in ~/.hermes/.env.

Verify the key file without exposing the secret:

test -f ~/.hermes/.env && stat -c '%a %n' ~/.hermes/.env

Success looks like 600 /home/you/.hermes/.env (or the equivalent path on your system). If the mode is broader than 600, run chmod 600 ~/.hermes/.env.

If you prefer to manage the key yourself, add it to that file without printing it into shell history:

mkdir -p ~/.hermes
chmod 700 ~/.hermes
read -rsp 'MiniMax API key: ' MINIMAX_KEY; printf '\n'
printf 'MINIMAX_API_KEY=%s\n' "$MINIMAX_KEY" >> ~/.hermes/.env
unset MINIMAX_KEY
chmod 600 ~/.hermes/.env
hermes model

Then select MiniMax and MiniMax-M3. Do not reuse a pay-as-you-go key with a Token Plan Subscription Key or vice versa; each path draws from a different billing source.

Command map

Job	Command or action	Observable success state
Check Hermes	hermes doctor	Doctor completes without a blocking install error
Configure provider	hermes model	MiniMax global and MiniMax-M3 are selected and saved
Start interactive use	hermes	A Hermes prompt opens using the configured model
Run one smoke test	hermes chat --provider minimax --model MiniMax-M3 -q "Reply with exactly: MINIMAX_OK"	Output contains MINIMAX_OK
Confirm the key file mode	stat -c '%a %n' ~/.hermes/.env	Output mode is 600
Switch models later	/model inside a session for already-configured models; re-run hermes model to add or re-authenticate a provider	Provider list reflects the change

The command syntax above was checked against local Hermes Agent v0.19.0 on July 31, 2026. Run hermes update if your version is older.

Smoke-test the connection

Run a small one-shot request:

hermes chat --provider minimax --model MiniMax-M3 \
  -q "Reply with exactly: MINIMAX_OK"

Expected success output:

MINIMAX_OK

A response containing MINIMAX_OK proves that Hermes can resolve the provider, read the credential, reach MiniMax, and invoke M3.

For normal interactive work, start Hermes with:

hermes

Inside a running Hermes session, /model switches among already-configured models. Re-run hermes model when you need to add a provider, re-authenticate, or refresh the catalog.

The model-pin rule

The model is MiniMax-M3 exactly. Different names that look similar:

• minimax-m3 — wrong case; fails.
• MiniMax/M3 — wrong slash; this is an aggregator-style alias, not a direct-MiniMax identifier.
• MiniMax-M3 — correct, direct MiniMax.

# Correct
hermes config set provider.minimax.default_model "MiniMax-M3"
hermes chat --provider minimax --model MiniMax-M3 -q "Reply with OK"

# Don't
hermes config set provider.minimax.default_model "minimax-m3"  # wrong case

If the response fails, the failure is usually a missing API key or a model-name case mismatch.

Why direct, not via an aggregator

The direct path is the default recommendation for M3 access. Three reasons:

1. Cost. Going direct avoids aggregator markup on every request.
2. Latency. Direct is faster than an aggregator hop.
3. Privacy. The request goes to MiniMax’s servers, not through an intermediate.

If you need aggregator routing for cross-vendor fallbacks, use the dedicated OpenRouter path; the OpenRouter guide covers that. Don’t put an aggregator in front of MiniMax for ordinary M3 work.

MiniMax-specific quirks

Three details that don’t apply to other providers on Hermes:

1. The model string is the only accepted alias. MiniMax-M3 resolves; MiniMax/M3 does not.
2. Token usage reports back in a different field name from Anthropic and OpenAI. Hermes logging normalizes it, but raw responses carry output_tokens_count rather than output_tokens. Custom loggers need to account for the difference.
3. Cross-region routing is automatic. MiniMax routes across regions for latency. You do not need to set a region; it picks. This is invisible until one region has an outage and the latency spikes; that’s when “automatic” starts costing you.

Troubleshooting

401 or “invalid API key”

Confirm that you copied a current MiniMax key. Token Plan uses a dedicated Subscription Key; pay-as-you-go uses a standard API key. Check for trailing spaces and re-run hermes model. Never post the key in a screenshot.

The key exists but has no usable resources

If you are on Token Plan, confirm your subscription is active, you have Credits attached, or a team owner assigned your seat. Then retry with the same key.

Requests work, then stop

Check the MiniMax console usage bar. You may have hit the rolling five-hour or weekly window on Token Plan, or run out of pay-as-you-go balance. Options are to wait, upgrade, or switch providers deliberately.

The model is missing from the picker

Run:

hermes model --refresh

Then choose MiniMax again. If MiniMax-M3 still does not appear, update Hermes and check the live provider docs.

Security and cost controls

Treat the key like a paid credential. Keep ~/.hermes/.env owner-readable only, do not commit it, do not paste it into prompts, and rotate or replace it if exposed. The account holder is responsible for activity on the account per MiniMax’s paid-service terms.

If you use a Token Plan, keep the billing paths distinct:

• Subscription Key draws from the included plan allowance, then eligible purchased Credits.
• Standard pay-as-you-go key draws from the wallet balance.

That separation prevents a quota reset from silently becoming an unexpected metered bill.

When not to use this guide

• You are choosing a subscription tier. Use the MiniMax Token Plan setup guide instead.
• You need a cross-vendor fallback. Use the OpenRouter guide and keep MiniMax in a separate fallback slot.

Keep this setup current

MiniMax changes model coverage and API behavior. Hermes changes model catalogs and setup flows. Before buying or debugging, re-check:

1. the Hermes provider docs;
2. the MiniMax Hermes integration page;
3. the live usage bar and the current price page shown in your MiniMax account.

Sources

• Hermes Agent AI providers — used for: native provider id minimax, env var MINIMAX_API_KEY, the interactive hermes model setup flow, and the MINIMAX_API_KEY env override. Verified July 31, 2026.
• MiniMax Token Plan pricing — used for: Token Plan tier prices and Subscription Key semantics. Verified July 31, 2026.
• MiniMax Token Plan Hermes integration — used for: installation and hermes model provider picker steps. Verified July 31, 2026.
• ABS companion: MiniMax Token Plan: Plans, Limits, and Hermes Agent Setup — used for: the full subscription rundown, tier table, and Token Plan caveats.

Last verified: July 31, 2026 against Hermes Agent v0.19.0 (2026.7.20) on the senior-dev profile. Live model: MiniMax-M3. Re-run hermes --version before following a flag whose number may have shifted.