> For the complete documentation index, see [llms.txt](/llms.txt).

# Architecture

MetaMask Agent Wallet exposes wallet operations through the `mm` CLI, backed by the `@metamask/agentic-sdk` package.

## CLI and session[​](#cli-and-session "Direct link to CLI and session")

- Install `@metamask/agentic-cli` to get the `mm` binary.
- Session data is stored at `~/.metamask/session.json` with restricted file permissions.
- Run `mm reset` to clear local session state.

## Wallet modes[​](#wallet-modes "Direct link to Wallet modes")

| Mode          | Keys                                          | Signing model                         |
| ------------- | --------------------------------------------- | ------------------------------------- |
| server-wallet | Cubist TEE-backed custody                     | Async jobs with optional MFA approval |
| BYOK          | User-supplied mnemonic (optionally encrypted) | Local signing; immediate results      |

See [Choose your wallet mode](/agent-wallet/get-started/choose-wallet-mode/).

## Server-wallet async model[​](#server-wallet-async-model "Direct link to Server-wallet async model")

When you submit a signing or transaction request in server-wallet mode:

1. The CLI submits the request to the wallet service.
2. The service may simulate the transaction, run Transaction Shield, and evaluate policies.
3. If policy requires human approval, the job enters an `AWAITING_MFA` state until you approve via MetaMask Mobile or email.
4. The CLI returns a `pollingId` unless you pass `--wait`.

Track pending work:

```
mm wallet requests list
mm wallet requests watch --polling-id <POLLING_ID>

```

## REPL vs headless[​](#repl-vs-headless "Direct link to REPL vs headless")

- **REPL** — Run `mm` with no arguments on a TTY for an interactive shell.
- **Headless** — Pass flags explicitly or use `--format json` for machine-readable output in scripts and agents.

## Next steps[​](#next-steps "Direct link to Next steps")

- [Security](/agent-wallet/concepts/security/)
- [Skills for agents](/agent-wallet/concepts/skills-for-agents/)