Skip to main content
This tutorial takes you from an empty machine to a local language model that reads and moves RGB assets on signet. Every piece runs on your computer: the model runs through QVAC, the reasoning engine is KaleidoMind, the tools come from kaleido-mcp, and the RGB Lightning Node runs in Docker through KaleidoCLI. The only network calls go to your node, to the signet KaleidoSwap API, and to the Bitcoin and RGB services the node itself needs.
Everything here runs on signet, with test coins that have no value. Do not reuse a seed or a password from this tutorial anywhere else.

Prerequisites

No API key and no hosted LLM are needed.

1. Start a Signet RGB Lightning Node

Install KaleidoCLI with its install script. It is not on PyPI yet, so pip install will not find it:
Create and start one node with the signet defaults, then initialise and unlock its wallet:
KaleidoCLI calls this network mutinynet; it is the same signet that the KaleidoSwap signet API and the RGB faucet use. Write down the mnemonic that kaleido node init prints. If port 3001 is already taken, kaleido setup picks the next free port. kaleido node list shows the URL; use it as RLN_NODE_URL in the steps below.
The Node Environments page covers running several nodes, switching between them, and reading logs.

2. Fund the Node

RGB assets live on Bitcoin UTXOs, so the node needs a little signet BTC before it can receive anything.
1

Get signet BTC

Print an on-chain address and send it coins from the public Mutinynet faucet. The faucet asks you to sign in with GitHub or to pay a small Lightning invoice:
Signet blocks arrive about every 30 seconds. Check with kaleido wallet balance.
2

Create UTXOs for RGB

Split some of that BTC into UTXOs that can hold RGB allocations:
3

Get test RGB assets

Open the KaleidoSwap RGB faucet and sign in with GitHub. Copy the USDT or XAUT asset ID it lists, and create an RGB invoice for it:
Paste the invoice in the faucet’s RGB on-chain tab. Each claim sends 100 USDT or 0.1 XAUT, up to 5 claims a day. Once the transfer confirms, kaleido asset refresh followed by kaleido asset list shows the asset. The faucet’s Lightning tab needs a route to your node, so it only works after the next step.
4

Buy a channel from the KaleidoSwap LSP

Swaps and Lightning payments need a channel. The KaleidoSwap LSP opens one to your node, optionally with USDT or XAUT on its side, and you pay a fee on-chain:
  • Channel size: 50,000 to 1,000,000 sat, with up to 1,000 USDT or XAUT per channel. A 200,000 sat channel costs about 3,400 sat in fees.
  • With an agent: Buy a channel from the KaleidoSwap LSP preloaded with 10 USDT runs kaleidoswap_lsp_get_info, kaleidoswap_lsp_quote_asset_channel and kaleidoswap_lsp_create_asset_channel. Pay the fee to the address the order returns.
  • In KaleidoSwap Desktop: Channels → Order New Channel.
Allow a few blocks for the channel to open. Swap limits per trade are 0.000001 to 0.01 BTC and 0.5 to 1,000 USDT or XAUT.

3. Run kaleido-mcp on Signet

KALEIDO_NETWORK=signet points kaleido-mcp at https://api.signet.kaleidoswap.com and Spark’s test network. Point RLN_NODE_URL at the node from step 1:
The server logs network: signet and waits on stdio. You do not need to keep it running by hand: the agent in the next step starts it as a child process. WDK_SEED is optional here, and plain npx does not install the Spark wallet package; without them the Spark tools stay off and the RGB, DEX, payment and market tools still work. See MCP Servers for every variable.
Want to try the tools before writing any code? Add the same command to Claude Desktop or Claude Code with the config in Client Configuration, then ask for your RGB balance. The rest of this tutorial swaps that hosted model for a local one.

4. Wire a Local QVAC Model with KaleidoMind

Want a ready-made project instead? npm create @kaleidorg/mind my-agent generates the RGB agent example with start:offline (no model, no node), start:mock (local model, fake node), eval:mock and start (your node) scripts. Set RLN_NODE_URL before npm start.
Create a project and install the engine, the QVAC SDK, and the MCP client:
The current KaleidoMind package requires @qvac/sdk >=0.20.0 and is tested with 0.21.0. Save this as agent.mjs:
agent.mjs
Run it:
The first start downloads the model. Every fund-moving tool pauses on the onConfirm callback, so nothing leaves the node until you type y.
This is a minimal host. The @kaleidorg/mind README and the examples/node-minimal and examples/rgb-agent folders in the kaleido-mind repository go further, with skills, recipes, and a larger model. The example loads Qwen3.5 2B (about 1.3 GB), which handled every signet RGB wallet task in our tests. QWEN3_5_4B_MULTIMODAL_Q4_K_M (about 2.7 GB) is as accurate but about twice as slow; the 0.8B model loops on wallet actions. The token caps in the sample leave room for its reasoning before the answer.

5. Prompts to Try

Go read-only first, then receive, then spend. KaleidoMind may call the legacy rln_* names for the same tools; kaleido-mcp serves both. To try a send without a second wallet, ask a friend for an RGB invoice, or create one on a second node with kaleido node create.
An atomic swap settles over Lightning, so the node needs a channel with the KaleidoSwap maker that carries the asset. The quickest way to get one on signet is to buy it from the LSP: Buy a channel from the KaleidoSwap LSP preloaded with 10 USDT runs kaleidoswap_lsp_quote_asset_channel and kaleidoswap_lsp_create_asset_channel, which you pay on-chain. Allow a few blocks for the channel to open before you swap.

Mock Mode: No Node, No Funds

To build the agent logic before the node is ready, or in CI, swap the MCP source for the stateful mock wallet in @kaleidorg/mind/testing. It is bound to the same tool contract, so the code that drives it later drives a real node:
mock.mjs
scriptedProvider() needs no model at all. Replace it with the QVAC provider from step 4 to test a real model against the mock wallet, then replace wallet.registry() with new ToolRegistry([kaleido]) to go live.

Troubleshooting

The installer puts kaleido in a user script directory that may not be on your PATH yet. Open a new terminal, or follow the path the installer printed. See CLI Installation.
Run kaleido node info. If it fails, start the containers with kaleido node up and unlock with kaleido node unlock; the wallet locks again on every restart. Then check that RLN_NODE_URL matches the URL that kaleido node list marks as active.
Run kaleido asset refresh and wait for a confirmation. If the node has no free UTXOs, the invoice cannot be created or settled: run kaleido wallet create-utxos again after funding with BTC.
The payer fetches the transfer data from an RGB proxy listed in the invoice. Create the invoice with kaleido asset invoice, which adds the default proxy, or name the proxy in your prompt as in the table above.
Confirm kaleido-mcp logged network: signet. An explicit KALEIDOSWAP_API_URL or KALEIDO_API_URL in your environment overrides the preset.
Check wdk_list_channels: you need a usable channel with the maker that carries the asset you are buying or selling. Without one the quote works but settlement cannot.
Small models are weak at open-ended planning. Phrase requests concretely, as in the prompts above, or load a larger QVAC model. KaleidoMind’s recipes handle the multi-step flows deterministically so the model only fills slots.
More fixes are in AI Tools Troubleshooting.

Ideas for Hackathon Projects

Voice wallet

QVAC also runs speech-to-text and text-to-speech locally. createQvacVoice and runVoiceAssistant in @kaleidorg/mind/qvac give you a hands-free loop with a spoken confirmation before every spend.

An agent that pays for APIs

Let the agent find a paid API with search_paid_apis, then pay it per call over Lightning with the mpp_* and l402_* tools. No signups, no API keys.

Autonomous swap bot

Watch prices with l402_get_price and kaleidoswap_get_spreads, and rebalance between BTC and USDT with atomic swaps. Keep the confirmation gate on until the decisions look right.

RGB issuance

Issue a ticket or loyalty token as a new RGB asset with rln_issue_asset (it needs free colorable UTXOs), or from the CLI with kaleido asset issue nia.