psyb0t/monero repository overview

Source⁠ | Project page⁠

⁠docker-monero

Your own Monero node with programmatic wallets, in one container. It runs the official monerod and monero-wallet-rpc releases and puts an HTTP API and an MCP server in front of them, so scripts and AI agents can read the chain, open wallets, check balances, and send XMR. The node also serves the restricted RPC that Cake Wallet and other wallets connect to.

⁠What's inside

Binaries come from getmonero.org and are checked against pinned SHA-256 hashes at build time. The image runs as a non-root user and works with a read-only root filesystem.

⁠Quick start

Try it on regtest first: a private offline chain where you mine blocks on demand, so nothing touches real money.

TOKEN=$(openssl rand -hex 32)
docker run -d --name monero -p 127.0.0.1:8080:8080 \
  -e DOCKER_MONERO_API_TOKEN=$TOKEN -e DOCKER_MONERO_NETWORK=regtest \
  psyb0t/monero
until curl -fs localhost:8080/ready >/dev/null; do sleep 1; done

xmr() { curl -s -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' "$@"; }

xmr -X POST localhost:8080/v1/wallets -d '{"name":"alice","password":"pw"}'
ADDR=$(xmr localhost:8080/v1/wallets/alice/addresses | jq -r .primaryAddress)
xmr -X POST localhost:8080/v1/node/regtest/generate-blocks -d "{\"count\":100,\"address\":\"$ADDR\"}"
xmr localhost:8080/v1/wallets/alice/balance

For mainnet, use the compose file:

curl -LO https://raw.githubusercontent.com/psyb0t/docker-monero/main/docker-compose.yml
curl -L -o .env https://raw.githubusercontent.com/psyb0t/docker-monero/main/.env.example
# Set DOCKER_MONERO_API_TOKEN in .env. For the default DOCKER_MONERO_DATA_PATH:
mkdir -p ./data
sudo chown 10001:10001 ./data
docker compose up -d

The first mainnet sync takes days and about 105 GiB of disk pruned. GET /v1/node/info shows the progress.

⁠Using the wallets

A wallet must be open to be read or spent from. Opening starts a wallet process, closing saves the wallet and stops it.

xmr -X POST localhost:8080/v1/wallets/alice/open -d '{"password":"pw"}'
xmr localhost:8080/v1/wallets/alice/status       # syncing? how far behind?
xmr -X POST localhost:8080/v1/wallets/alice/transfers \
  -d '{"destinations":[{"address":"4...","amount":"1500000000000"}],"dryRun":true}'
xmr -X POST localhost:8080/v1/wallets/alice/close

Amounts are strings of atomic units (1 XMR = 10^12). Sends are refused until the node and the wallet are both caught up, and dryRun prices a transaction without broadcasting it. Everything else is in docs/api.md⁠ and the OpenAPI spec at api/api.yml⁠.

⁠Write switches

Create or restore the wallets you need, then lock the deployment down:

• DOCKER_MONERO_READ_ONLY=true refuses every write: new or restored wallets, new subaddresses, sends. Opening, closing, and reading still work.
• DOCKER_MONERO_ALLOW_TRANSFERS=false refuses only sends.
• DOCKER_MONERO_MCP_ALLOW_TRANSFERS=true is the only way an MCP client can send. It is off by default.

⁠Cake Wallet and other remote wallets

Publish port 18089 and point the wallet at http://<your-host>:18089 as a custom node. That is monerod's restricted RPC: it serves what wallets need and none of the commands that control the node. Set DOCKER_MONERO_PUBLIC_NODE=true if you also want to advertise it to the network.

To require a login, set DOCKER_MONERO_RPC_LOGIN=username:password and enter the same username and password in the wallet's custom node settings. The username must be non-empty and contain no colon, and the password must have at least 16 characters. Empty keeps login disabled. See configuration.md⁠.

⁠MCP

Connect an MCP client to http://localhost:8080/mcp with Authorization: Bearer <token>. The tools and which ones each mode registers are in docs/mcp.md⁠.

⁠Agent integrations

An agent can drive a running docker-monero instance through a skill (REST routes, MCP tools, and the rules around wallets and sending) and, for stdio-only MCP clients, a bridge plugin. Restart the agent session after installing.

Claude Code asks for the instance URL and the API token when you enable the plugin:

claude plugin marketplace add psyb0t/agents
claude plugin install monero@psyb0t

Codex:

codex plugin marketplace add psyb0t/agents
codex plugin add monero@psyb0t

OpenClaw, the skill and the MCP bridge plugin:

openclaw skills install @psyb0t/monero
openclaw plugins install clawhub:@psyb0t/monero

The skill and the bridge read MONERO_URL, for example http://localhost:8080, and MONERO_TOKEN, the value of DOCKER_MONERO_API_TOKEN. A client that speaks Streamable HTTP can skip the bridge and connect to http://localhost:8080/mcp with an Authorization: Bearer <token> header. The server is also listed in the MCP registry as io.github.psyb0t/monero.

This section is for using the service from an agent. To change this repository, read AGENTS.md.

⁠Configuration

All settings are DOCKER_MONERO_* environment variables, listed with defaults in docs/configuration.md⁠. The only required one is DOCKER_MONERO_API_TOKEN. Compose mounts the host directory DOCKER_MONERO_DATA_PATH (default ./data) at /data. It must be writable by UID/GID 10001; back up its wallets subdirectory.

Give the container time to stop: it saves every open wallet and lets monerod flush its database. Use docker stop -t 180; the compose file sets stop_grace_period.

⁠Docs

• docs/api.md⁠: amounts, wallet lifecycle, sync, sending, error codes
• docs/configuration.md⁠: every variable, ports, disk
• docs/mcp.md⁠: MCP tools
• docs/security.md⁠: what the service protects and what you have to
• docs/architecture.md⁠: processes, startup, shutdown, crash handling
• docs/development.md⁠: building and testing from source

⁠Development

make build      # static binary in build/
make test       # unit tests
make test-api   # the real image on regtest
make lint

Details in docs/development.md⁠.

⁠License

WTFPL⁠. Monero itself is under its own BSD-3-Clause license.