MUTX Documentation

MUTX is a local authority layer for Solana wallets used by AI agents.

The public product has two parts:

• mutx: the terminal UI that stores wallet state, shows approvals, and signs operations
• mutx-link: the agent interface (MCP server + CLI) that exposes wallet tools to agents

mutx-link is intentionally thin. It forwards requests to MUTX over a local Unix socket and does not hold wallet secrets.

What you get

• Wallet operations without handing agents raw private keys
• Manual approval in the TUI when you want direct control
• Bounded autonomy through Short Lived Keys (SLK)
• The same model across local binaries and containers

What MUTX can do

• Create or import Solana wallets
• Send and receive SOL
• List, send, and close SPL token accounts
• Swap through Jupiter or Raydium
• Connect wallets to dApps with WalletConnect
• Manage an address book
• Expose wallet operations over stdio or HTTP through MCP
• Expose wallet operations as CLI subcommands for scripts and Skills-based agents

Start here

• Installation
• Quick Start
• TUI Guide
• MCP Integration

This documentation covers the public operator surface only. Internal services and licensing internals are intentionally excluded.

Getting Started

This section covers how to install mutx and mutx-link, then get to a working approval flow with an MCP client.

Installation

You can run MUTX as local binaries or as containers.

Components

• mutx: interactive terminal application; this is the authority process
• mutx-link: MCP server + CLI; this is the agent-facing process

In normal use, you run both.

Binary install

MUTX

Linux x86_64:

curl -LO https://download.mutx.net/mutx/latest/mutx-linux-x86_64
chmod +x mutx-linux-x86_64
sudo mv mutx-linux-x86_64 /usr/local/bin/mutx

macOS Intel:

curl -LO https://download.mutx.net/mutx/latest/mutx-macos-intel
chmod +x mutx-macos-intel
sudo mv mutx-macos-intel /usr/local/bin/mutx

macOS Apple Silicon:

curl -LO https://download.mutx.net/mutx/latest/mutx-macos-arm
chmod +x mutx-macos-arm
sudo mv mutx-macos-arm /usr/local/bin/mutx

Link (MCP server + CLI)

Linux x86_64:

curl -LO https://download.mutx.net/link/latest/mutx-link-linux-x86_64
chmod +x mutx-link-linux-x86_64
sudo mv mutx-link-linux-x86_64 /usr/local/bin/mutx-link

macOS Intel:

curl -LO https://download.mutx.net/link/latest/mutx-link-macos-intel
chmod +x mutx-link-macos-intel
sudo mv mutx-link-macos-intel /usr/local/bin/mutx-link

macOS Apple Silicon:

curl -LO https://download.mutx.net/link/latest/mutx-link-macos-arm
chmod +x mutx-link-macos-arm
sudo mv mutx-link-macos-arm /usr/local/bin/mutx-link

Verify

mutx --version
mutx-link --version

Container images

Published images:

• ghcr.io/mutx-net/mutx:latest
• ghcr.io/mutx-net/mutx-link:latest

Run MUTX interactively:

docker run --rm -it \
  -v "$HOME/.config/mutx:/home/mutx/.config/mutx" \
  -v "$HOME/.local/share/mutx:/home/mutx/.local/share/mutx" \
  -v /tmp/mutx:/tmp/mutx \
  ghcr.io/mutx-net/mutx:latest

Run Link in HTTP mode:

docker run --rm \
  -p 8000:8000 \
  -v /tmp/mutx:/tmp/mutx \
  ghcr.io/mutx-net/mutx-link:latest

The shared /tmp/mutx mount is mandatory. Without it, the Link container cannot reach the MUTX socket and the two processes will not communicate.

Common deployment shapes

Host MUTX plus containerized Link:

mutx

docker run --rm \
  -p 8000:8000 \
  -v /tmp/mutx:/tmp/mutx \
  ghcr.io/mutx-net/mutx-link:latest

Containerized MUTX plus containerized Link:

docker run --rm -it \
  -v "$HOME/.config/mutx:/home/mutx/.config/mutx" \
  -v "$HOME/.local/share/mutx:/home/mutx/.local/share/mutx" \
  -v /tmp/mutx:/tmp/mutx \
  ghcr.io/mutx-net/mutx:latest

docker run --rm \
  -p 8000:8000 \
  -v /tmp/mutx:/tmp/mutx \
  ghcr.io/mutx-net/mutx-link:latest

Quick binary start

If you want the shortest local path, run the binaries directly:

mutx
mutx-link

Requirements

• A terminal with TTY support for mutx
• MUTX must be running before mutx-link
• Solana RPC access for wallet and swap operations

Continue to Quick Start.

Quick Start

This is the shortest path to a working approval flow.

1. Start the daemon

mutx daemon

This starts the headless service that manages wallets and authorization.

2. Start the TUI

mutx

On first run, create or import a wallet from the Wallets tab:

1. Press n to create a wallet, or i to import one
2. Choose the network for the wallet
3. Use password protection unless you are testing on throwaway wallets
4. Press r to display the receive address
5. Press b to refresh balances

3. Connect an agent

Local stdio mode (default):

mutx link

HTTP mode:

mutx link serve --mode http --bind 0.0.0.0:8000

4. Configure your MCP client

Minimal local configuration:

{
  "mcpServers": {
    "mutx": {
      "command": "mutx",
      "args": ["link"]
    }
  }
}

If you run Link over HTTP, point your client to /mcp on the chosen host and port.

5. Approve the first request

When the client calls a sensitive tool:

• the request appears in the Requests tab
• press y to approve
• press n to deny

WalletConnect session proposals are handled from the DApps tab rather than the Requests queue.

6. Verify Link is working

mutx link wallet list

If you see your wallets printed, the socket is healthy and any MCP client will be able to reach MUTX.

See the MCP Setup guide for detailed configuration, or Agent Integration for client-specific instructions.

TUI Guide

mutx is the primary operator interface. It stores local state, renders approval flows, and is the only process that can unlock wallets and sign.

• Approvals & Requests — Review MCP actions and WalletConnect prompts
• Wallet Management — Create, import, and operate wallets
• Keybindings — Complete keyboard shortcut reference

Approvals & Requests

The Requests tab is the approval surface for MCP-driven actions.

When an agent asks MUTX to do something sensitive without an SLK, the TUI stores the request locally and waits for operator input.

What shows up here

• wallet list exposure requests
• wallet details and balance requests
• receive address requests
• SOL send requests
• swap requests
• address book list and add requests
• SLK creation requests

Approval flow

1. The MCP client calls a tool
2. Link forwards the request to MUTX
3. The request appears in the TUI
4. You approve with y or deny with n
5. The MCP client receives the result

WalletConnect is separate

WalletConnect does not use the Requests queue for session proposals. Pairings, proposals, and live sessions are handled from the DApps tab.

Request history

Approved and denied requests remain useful as an audit trail:

• d removes a request from the visible history
• e copies the explorer URL when one exists

For deeper troubleshooting, use the Logs tab or the mutx logs export command.

Wallet Management

The Wallets tab is where you create, import, inspect, and operate wallets.

Supported network

Wallet support is currently Solana.

Per wallet you can work against:

• devnet
• testnet
• mainnet
• custom RPC

New wallets default to devnet, which is the safest place to test.

Create a wallet

From the Wallets tab:

1. Press n
2. Enter a wallet name
3. Choose the Solana cluster
4. Choose how the wallet should be protected

Import a wallet

Press i to import from a seed phrase or private key.

Protection modes

• Password (default) — Requires password for sensitive operations
• KeyFile — Uses a local file or remote URL as the encryption key
• Cleartext — No password; suitable only for temporary test wallets

Common actions

With a wallet selected, the default shortcuts are:

• r show receive address
• t transfer SOL
• s open swap flow
• b refresh balances
• h show transaction history
• o toggle token account view
• z close empty token accounts
• x export seed phrase or private key
• m rename wallet
• p pin or unpin wallet in the sidebar
• d delete wallet

Airdrops

The a shortcut requests faucet SOL on devnet and testnet.

Mainnet wallets do not support airdrops.

Wallet details

Press Enter on a wallet to inspect wallet-specific settings and network configuration. This is where custom RPC endpoints and per-wallet settings appear.

Keybindings

All keybindings are configurable. Defaults are listed below.

Global

Wallets

Requests

Address Book

DApps

SLK and Logs

Web UI

MUTX includes a browser-based Web UI (mutx-web) that provides full feature parity with the Terminal UI.

Starting the Web UI

The Web UI requires the daemon (mutxd) to be running.

# Start the daemon
mutxd

# Start the Web UI
mutx-web
# Opens at http://127.0.0.1:8080

Features

The Web UI provides all the same operations as the TUI:

• Dashboard — Portfolio overview with Matrix rain animation
• Wallets — Create, import, send SOL/tokens, swap, receive (QR code), transaction history, per-wallet settings
• Keys (SLK) — Create with per-token budgets, revoke, delete, duplicate, usage history
• Requests — Approve/deny agent requests, clear history
• Contacts — Address book management (add, edit, delete)
• DApps — WalletConnect pairing and session management
• Logs — Real-time log viewer with search and filtering
• License — Status, tier comparison, coupon redemption, USDC purchase from wallet
• Settings — Theme, log level, RPC endpoint overrides

Architecture

The Web UI is a pure daemon client:

Browser → mutx-web (Axum HTTP) → mutxd (daemon) → Solana RPC

• mutx-web connects to the daemon via Unix socket (mutx.sock)
• All data comes from the daemon — the Web UI has no direct DB or RPC access
• Real-time updates via Server-Sent Events (SSE)
• Catppuccin Mocha theme (matching the TUI)

Configuration

# Custom bind address
mutx-web --bind 0.0.0.0:3000

# Custom socket directory
mutx-web --socket-dir /path/to/sockets

By default, the Web UI binds to 127.0.0.1:8080 (local only). To expose on the network, use --bind 0.0.0.0:PORT.

MCP Integration

mutx-link exposes MUTX wallet operations to MCP-compatible agents.

The boundary is simple:

• mutx holds local state and wallet access
• mutx-link forwards requests to MUTX
• communication between them happens over a Unix socket at /tmp/mutx/mutx.sock

Link also supports a CLI mode (mutx-link wallet list, etc.) for Skills-based agents and scripts that prefer shell commands over MCP.

• Setup — Configure the MCP server
• Agent Integration — Connect Claude Code, Claude Desktop, and custom agents
• Available Tools — Complete tool reference
• SLK (Short Lived Keys) — Autonomous authorization tokens

MCP Setup

Link supports local stdio transport and streamable HTTP transport.

Prerequisite

Start the daemon first:

mutx daemon

Link expects the MUTX socket at:

/tmp/mutx/link.sock

You can override the socket path with MUTX_SOCKET_PATH or mutx link --link-socket-path ....

stdio mode

mutx link

This is the default mode and the best choice when the agent runs on the same machine.

Example client configuration:

{
  "mcpServers": {
    "mutx": {
      "command": "mutx",
      "args": ["link"]
    }
  }
}

Note: The standalone mutx-link binary is still available and works identically. Use it if you prefer a dedicated binary or in Docker containers.

HTTP mode

mutx link serve --mode http --bind 0.0.0.0:8000

HTTP mode exposes:

• MCP endpoint: http://HOST:8000/mcp
• health check: http://HOST:8000/health

Use this mode when:

• the agent cannot spawn local processes
• you want to front MUTX with a container
• you need a shared MCP endpoint on a trusted local network

CLI mode

Link also exposes all 17 MCP tools as CLI subcommands:

mutx link wallet list
mutx link wallet balance <wallet>
mutx link wallet send <wallet> <to> <amount>
mutx link slk info
mutx link address-book list

Use --json for machine-readable output. Use --link-socket-path to override the default socket location.

Container example

docker run --rm \
  -p 8000:8000 \
  -v /tmp/mutx:/tmp/mutx \
  ghcr.io/mutx-net/mutx-link:latest

If MUTX is also containerized, mount the same /tmp/mutx directory into both containers.

Verifying the connection

With the daemon running, confirm the socket is reachable:

mutx link wallet list

If you see your wallets listed, the socket connection is healthy and any MCP client configured with {"command": "mutx", "args": ["link"]} will work.

Troubleshooting

For verbose logging, set RUST_LOG=mutx_link=debug before starting Link.

Operational notes

• Link is stateless
• if the daemon is not reachable, tool calls fail immediately
• wallet approvals still happen in the terminal, even when Link is served over HTTP

Agent Integration

How to connect MUTX to specific MCP clients.

Claude Code

Add to ~/.claude.json or your project .mcp.json:

{
  "mcpServers": {
    "mutx": {
      "command": "mutx",
      "args": ["link"]
    }
  }
}

The daemon must be running before the Claude Code session starts. Start it with mutx daemon. The agent spawns mutx link as a subprocess in stdio mode. Approvals appear in the MUTX Requests tab.

Claude Desktop

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mutx": {
      "command": "/usr/local/bin/mutx",
      "args": ["link"]
    }
  }
}

Claude Desktop may not inherit your shell PATH. Use the full path to mutx.

Custom agents (SDK)

stdio transport

Spawn mutx link as a subprocess and wire stdin/stdout. This works with any MCP SDK that supports stdio transport.

HTTP transport

Run Link in HTTP mode:

mutx link serve --mode http --bind 0.0.0.0:8000

Point your SDK’s HTTP transport at http://HOST:8000/mcp.

Docker-based agents

When the agent cannot spawn local processes, run Link in a container:

docker run --rm -p 8000:8000 \
  -v /tmp/mutx:/tmp/mutx \
  ghcr.io/mutx-net/mutx-link:latest

The agent connects to http://localhost:8000/mcp. MUTX can run natively or in its own container – both just need to share /tmp/mutx.

CLI mode

For shell scripts and Skills-based agents that prefer commands over MCP:

mutx link wallet list
mutx link wallet balance <wallet>
mutx link wallet send <wallet> <to> <amount>
mutx link slk request --name "trading" --wallets "Main" --can-send --duration 3600
mutx link address-book list
mutx link wc sessions

Full command groups:

mutx link wallet {list,receive,send,details,balance,transactions,token-list,token-send,swap}
mutx link slk {request,info,revoke}
mutx link address-book {list,add}
mutx link wc {connect,sessions,disconnect}

Use --json for machine-readable output. Use --link-socket-path to override the default socket location.

Available MCP Tools

MUTX exposes 17 MCP tools.

Most tools follow one of these patterns:

• approval in the terminal
• autonomous execution with a valid SLK
• direct execution for low-risk session and token lifecycle operations

Conventions

• Wallets are referenced by short ID or wallet name
• slk is optional on tools that support autonomous execution
• wallet_connect creates a pairing attempt, but the user still approves the WalletConnect proposal inside the terminal

Wallet Tools

wallet_list

List available wallets.

wallet_details

Get wallet name, address, and network.

wallet_balance

Refresh and return SOL plus token balances.

wallet_receive

Get a wallet’s receive address.

wallet_send

Send SOL to an address.

wallet_token_list

List SPL tokens held by a wallet.

wallet_token_send

Send SPL tokens.

wallet_swap

Swap tokens via Jupiter or Raydium.

wallet_transactions

Transaction history with optional filters.

Filter fields:

Address Book

address_book_list

List saved contacts.

address_book_add

Add a contact.

WalletConnect

wallet_connect

Submit a WalletConnect pairing URI. The session proposal is approved in the terminal.

wallet_sessions

List active WalletConnect sessions. No parameters.

wallet_disconnect

Disconnect a WalletConnect session.

SLK Management

request_slk

Request a Short Lived Key. Always requires terminal approval.

get_slk_info

Check SLK status, remaining budget, expiry, wallets, and permissions.

slk_revoke

Revoke an active SLK.

Common Workflows

Check a wallet balance

1. wallet_list — get available wallets
2. Pick a wallet ID or name from the response
3. wallet_balance — returns SOL and token balances

Send SOL with an SLK

1. request_slk with can_send, max_amount_per_tx, total_amount, whitelist
2. Operator approves in the terminal
3. Agent receives the SLK token
4. wallet_send with the SLK — executes without further approval

Execute a swap autonomously

1. request_slk with can_swap, max_slippage_bps
2. Operator approves
3. wallet_swap with the SLK — quote is fetched and swap executes within slippage bounds

SLK (Short Lived Keys)

Short Lived Keys allow AI agents to perform wallet operations autonomously within explicit limits.

An SLK is not a wallet key. It is a capability token issued by the TUI and checked on each MCP request.

Requesting an SLK

An agent calls request_slk with desired permissions. The request appears in the TUI’s Requests tab for human approval.

The operator can scope the SLK to specific wallets and address-book entries.

Permissions

• can_balance — View wallet balances
• can_receive — Get receive addresses
• can_send — Send SOL
• can_send_tokens — Send SPL tokens
• can_swap — Swap tokens via DEX
• can_sign — Sign messages

Constraints

• Wallet scope — Which wallets are visible to the SLK
• Address-book scope — Which contacts are visible to the SLK
• max_amount_per_tx — Maximum SOL amount per send
• total_amount — Total SOL budget
• whitelist — Allowed recipient addresses for SOL sends
• allowed_tokens / denied_tokens — Token-level allow or deny rules
• token_constraints — Per-token send budgets
• max_slippage_bps — Maximum allowed slippage for swaps
• duration_secs — Expiry window

Revocation and inspection

• get_slk_info returns status, budget, scope, and permissions
• slk_revoke immediately revokes a token
• revoked or expired SLKs are rejected without user interaction

When to use SLKs

Use an SLK when you want an agent to keep operating within a narrow boundary, for example:

• checking balances periodically
• sending capped payouts to a fixed whitelist
• executing swaps with a strict slippage ceiling

If you do not need autonomy, skip SLKs and keep the default approval flow.

Relay (Remote Access)

The MUTX relay enables remote AI agents to communicate with your local daemon over the internet. Without the relay, agents can only reach the daemon via local Unix socket.

How It Works

1. Your daemon connects outbound to relay.mutx.net via WebSocket.
2. Remote agents send requests to the relay with your unique relay code.
3. The relay forwards requests to your daemon.
4. Your daemon validates the SLK and processes the request (same as local).
5. Responses flow back through the relay to the agent.

The relay is a transparent pipe. All authorization (SLK validation, approval queues, budget tracking) happens locally in your daemon.

Setup

1. Enable Relay

In MUTX settings, enable relay mode:

relay_enabled = true

2. Register

The daemon registers with the relay server and receives:

• Relay code (MUTX-XXXX): Share this with agents so they can reach you.
• Relay secret: Used by the daemon to authenticate to the relay. Keep this private.

3. Share Credentials with Agents

Give the agent:

• Your relay code (e.g., MUTX-R7K3)
• An SLK token (created via the TUI or another trusted agent)

The agent uses both to send requests through the relay.

Agent Request Format

Agents send HTTP POST requests to https://relay.mutx.net/v1/request:

{
  "relay_code": "MUTX-R7K3",
  "envelope": {
    "slk": "slk_...",
    "request": {
      "type": "wallet_list",
      "request_id": "unique-id"
    }
  }
}

The response is a standard McpResponse JSON object.

Discovery

Agents can discover capabilities at:

GET https://relay.mutx.net/.well-known/mutx.json

This returns available tools, the request URL, and auth requirements.

Security

• SLK tokens control what agents can do (permissions, budgets, time limits).
• The relay never sees your wallet keys or makes authorization decisions.
• You can revoke relay access at any time by disabling relay mode or revoking the registration.
• All traffic is encrypted via TLS.

Disabling

Set relay_enabled = false in settings, or revoke the registration. The daemon disconnects immediately and agents can no longer reach you.

Reference

• Configuration — Paths, overrides, and runtime settings
• Deployment — Binary and container deployment patterns
• FAQ — Frequently asked questions

Configuration

MUTX uses XDG-style paths by default.

Paths

• Config directory: ~/.config/mutx/
• Data directory: ~/.local/share/mutx/
• Bootstrap file: ~/.config/mutx/config.toml
• Default socket path: /tmp/mutx/mutx.sock

After first run, most settings live in the SQLite database under the data directory. The TOML file becomes a minimal bootstrap file, mainly for db_path.

CLI and environment overrides

mutx supports these overrides:

• --config-dir or MUTX_CONFIG_DIR
• --data-dir or MUTX_DATA_DIR
• --socket-path or MUTX_SOCKET_PATH
• --log-file or MUTX_LOG_FILE
• --log-level or MUTX_LOG_LEVEL

Bootstrap example

db_path = "/home/alice/.local/share/mutx/mutx.db"

Runtime settings

The application persists settings such as:

• theme flavor: mocha, latte, macchiato, frappe
• log level
• log-to-file toggle
• vim navigation mode
• hidden balance mode
• dashboard animation toggle
• Solana network defaults and overrides
• custom RPC and explorer URL templates
• keybindings

Solana configuration

Supported default networks:

• devnet
• testnet
• mainnet
• custom

Available global overrides include:

• per-network RPC endpoints
• per-network explorer transaction URLs with {tx}
• per-network explorer address URLs with {addr}
• Jupiter API key
• Raydium API key

Deployment

This page covers the public deployment shapes for MUTX.

Local binaries

This is the simplest setup:

1. Run mutx
2. Run mutx-link
3. Configure the agent to spawn mutx-link

Use this when the operator, the TUI, and the agent all live on the same host.

Split local TUI plus containerized Link

This is useful when the agent expects an HTTP endpoint or when you want to keep the Link runtime isolated.

Requirements:

• MUTX running on the host
• shared socket directory mounted into the Link container

Example:

docker run --rm \
  -p 8000:8000 \
  -v /tmp/mutx:/tmp/mutx \
  ghcr.io/mutx-net/mutx-link:latest

Fully containerized

You can containerize both components, but MUTX still needs:

• -it for interactive terminal access
• persistent config and data volumes
• a shared /tmp/mutx mount so the Link container can reach the socket

Health checks

In HTTP mode, Link exposes:

• /health for liveness
• /mcp for the actual MCP transport

Logging

mutx can write structured logs to file and export them with:

mutx logs export

Useful flags:

• --category
• --level
• --since
• --until
• --encrypt

FAQ

General

What blockchains does MUTX support?

Currently Solana.

Is MUTX open source?

No. The public product is distributed as binaries and container images.

Where is my data stored?

All wallet data is stored locally in SQLite databases under ~/.local/share/mutx/. Private keys are encrypted with AES-256-GCM.

Does Link store wallet keys?

No. Wallet access stays in MUTX. Link forwards requests to the TUI over a local Unix socket.

Does the TUI need to be running for Link to work?

Yes. mutx-link depends on the TUI socket and cannot serve wallet operations by itself.

MCP

Can I run Link remotely?

Yes, using HTTP mode:

mutx-link serve --mode http --bind 0.0.0.0:8000

The MCP endpoint is /mcp and the health endpoint is /health.

What still requires human approval?

Anything you do without an SLK. request_slk itself also always requires approval.

Can an SLK be revoked immediately?

Yes. Use slk_revoke or revoke it from the TUI.

TUI

Can I use Docker for the TUI?

Yes, but it must run with an interactive TTY and persistent volumes for config, data, and the shared socket directory.

Which tab should I watch during operation?

• Requests for MCP approvals
• DApps for WalletConnect proposals and sessions
• Logs for troubleshooting and audit context