Quick Start¶

Prerequisites¶

Python 3.11+
Reticulum Network Stack (pip install rns)
LXMFy (pip install lxmfy or install from source)

Creating Your First Bot (Using the CLI)¶

The easiest way to start is using the LXMFy command-line tool.

Open your terminal in the directory where you want to create your bot project.
Run the create command:
```
lxmfy create my_first_bot
```
This command will generate the following files: * my_first_bot.py: Your main bot file, configured with sensible defaults. * cogs/: A directory for bot extensions (cogs). * cogs/__init__.py: Makes the cogs directory a Python package. * cogs/basic.py: An example cog with simple “hello” and “about” commands. * data/: A directory where the bot will store its data (using JSON by default). * config/: A directory where the bot stores its identity and announce status.

Review the :code:`my_first_bot.py` file:

from lxmfy import LXMFBot

bot = LXMFBot(
    name="my_first_bot",  # Bot name used in announces/identity
    announce=600,         # Announce interval in seconds (10 minutes)
    announce_immediately=True, # Announce on first run?
    admins=set(),         # Set of admin LXMF address hashes
    hot_reloading=False,  # Enable/disable hot reloading of cogs
    rate_limit=5,         # Max messages per minute per user
    cooldown=60,          # Cooldown period in seconds for rate limit
    max_warnings=3,       # Warnings before ban for spam
    warning_timeout=300,  # Time (seconds) before warnings reset
    command_prefix="/",   # Prefix for commands (e.g., /hello)
    cogs_dir="cogs",      # Directory to load cogs from
    cogs_enabled=True,    # Enable/disable loading cogs
    permissions_enabled=False, # Enable/disable the role-based permission system
    storage_type="json",  # Storage backend ("json" or "sqlite")
    storage_path="data",  # Path for storage files/database
    first_message_enabled=True, # Enable special handling for first messages
    event_logging_enabled=True, # Log events to storage?
    max_logged_events=1000,   # Max events to keep in log
    event_middleware_enabled=True, # Enable event middleware?
    announce_enabled=True,   # Enable/disable network announces
    signature_verification_enabled=False, # Enable/disable cryptographic signature verification
    require_message_signatures=False     # Require all messages to be signed
)

# To add an admin, find your LXMF address hash and add it here:
# bot.config.admins.add("your_lxmf_hash_here")
# bot.admins = bot.config.admins # Ensure the running instance knows

# Example of preparing an LXMF icon field (optional)
# from lxmfy import IconAppearance, pack_icon_appearance_field
# try:
#     icon_data = IconAppearance(icon_name="emoji_objects", fg_color=b'\xFF\xA5\x00', bg_color=b'\x8B\x45\x13') # Orange on Brown
#     bot.icon_field = pack_icon_appearance_field(icon_data) # Store for use in send/reply
# except Exception as e:
#     print(f"Could not prepare icon field: {e}")
#     bot.icon_field = None

if __name__ == "__main__":
    print(f"Starting bot: {bot.config.name}")
    print(f"Bot LXMF Address: {bot.local.hash}") # Prints the bot's address
    bot.run()

(Optional) Add Your Admin Hash: * Find your LXMF address hash (e.g., from your Reticulum client like Sideband or NomadNet). * Uncomment and edit the bot.config.admins.add(...) line in my_first_bot.py, replacing "your_lxmf_hash_here" with your actual hash.
Run Your Bot:
```
python my_first_bot.py
```
Your bot will start, print its LXMF address, potentially send an announce message over the Reticulum network, and begin listening for messages.

Interacting With Your Bot¶

Send a message to the bot’s LXMF address from your client.
Try the example command: Send /hello to the bot. It should reply with “Hello <your_hash>!”. If you uncommented the icon example above, this reply might also carry an icon.
Try the help command: Send /help.

Advanced Features¶

Once you’re comfortable with the basics, explore these advanced features:

Message Handlers:

Use @bot.on_first_message() to welcome new users
Use @bot.on_message() to handle all messages before command processing

Reliable Delivery:

Configure max_retries parameter in bot.send() for automatic retry on delivery failure
Use propagation_node parameter to route messages through specific LXMF propagation nodes

Security:

Enable signature_verification_enabled=True to enforce LXMF’s built-in signature verification
Set require_message_signatures=True to reject unsigned or invalid messages
Note: LXMF automatically signs all messages; LXMFy just enforces verification policy

See the Creating Bots guide and API Reference for detailed information on these features.

Next Steps¶

Explore the Creating Bots guide for more details on adding commands, using cogs, and different bot types.
Check the API Reference for detailed information on framework components.