SwarmAI Wrangler
Join

Workshop Guide: Your First Decentralized AI Agent

Welcome, Agent Wrangler! 🐝
Today, you'll equip a powerful AI assistant with a decentralized "brain" using the Swarm network. You'll complete a series of missions to give your agent new capabilities, competing on a live leaderboard to see who can become the top wrangler.
Let's get started!
Part 0: Pre-Flight Checklist
Before we begin the live missions, make sure you have your toolkit ready.
1. AI Agent Tool Installed
You should have one of the following AI agent applications installed on your laptop:
  • Claude Desktop: A user-friendly, chat-based interface.
  • Windsurf: A powerful, developer-focused editor with AI capabilities.
  • Cursor: An AI-first code editor.
If you haven't installed one yet, please do so now. Mentors are here to help!
2. Prerequisites
Make sure you have node (v18 or higher) and git installed on your machine.
3. Know Your 'Why'
To get a head start, check out this blog post explaining why AI needs to get decentralized and watch this short video introducing the concept of "postage stamps" for storing data.
Part 1: Setup & First Contact
Step 1: Get the Swarm MCP Server
First, you need the Swarm MCP server, which will act as the bridge between your AI agent and the Swarm network.
  1. Clone the repository: Open your terminal and run this command to download the code:
    git clone https://github.com/solar-punk-ltd/swarm-mcp.git
  2. Navigate into the directory:
    cd swarm-mcp
  3. Install dependencies:
    npm install
  4. Build the project: This compiles the code into a format your AI agent can use.
    npm run build
This command creates a dist folder inside your swarm-mcp directory. This is important for the next step!Troubleshooting Note: On macOS or Linux, you might encounter a "permission denied" error later. If you do, run the following command to make the server executable:
chmod +x dist/index.js
Step 2: Connecting Your Agent to Swarm
Now, we'll tell your AI agent how to use the server you just built. This involves configuring it to connect to our workshop's pre-funded Swarm Gateway. (This is a specific instance of the open-source Swarm Gateway, which you can explore on GitHub).
Your Agent's Secret Identity (BEE_FEED_PK)
Each of you has been assigned a unique private key. This is your agent's secret identity, allowing it to create and update its own personal log on Swarm.
  1. Get Your Key: Find your unique private key on the workshop portal at
    • Click “Join” (top right corner)
    • Provide a nickname
    • Click “Generate Identity”
    • Copy the Private Key to be used in the next step.
  2. Prepare the Configuration: The JSON snippet below is the core configuration for the MCP server.
    • First, replace /path/to/your/swarm-mcp with the actual, full path to the folder you just cloned.
    • Then, replace YOUR_UNIQUE_PRIVATE_KEY_HERE with the key you received from the workshop portal.
      {  
  "mcpServers": {  
    "Swarm": {  
      "command": "npx",  
      "args": [  
        "/path/to/your/swarm-mcp/dist/index.js"  
      ],  
      "env": {  
        "BEE_FEED_PK": "YOUR_UNIQUE_PRIVATE_KEY_HERE"  
      }  
    }  
  }  
}
  3. Configure Your AI Tool: Follow the instructions for your specific tool, and use the JSON config you have just prepared.
For Claude Desktop Users:
  1. Go to Settings > Developer > Local MCP servers and click "Edit Config".
  2. Add the prepared JSON configuration to the claude_desktop_config.json file.
  3. Save the file and restart Claude Desktop – and any time you make changes to the config make sure you restart Claude Desktop again.
  4. Verify the connection under the "Developer" tab. You should see "Swarm" listed as "running".
For Windsurf Users:
  1. Go to Settings > Windsurf Settings > Cascade > Manage MCPs.
  2. Click "View raw config" and add the prepared JSON configuration.
  3. Save the config, then go back to Manage MCPs and click "Refresh". The "Swarm" MCP should appear as operational.
For Cursor Users:
  1. Go to Settings > Cursor Settings > Tools & Integrations.
  2. In the "MCP Tools" section, click on "New MCP Server".
  3. Add the prepared JSON configuration to the mcp.json file.
  4. Save the file and check the status indicator next to the "Swarm" MCP name; it should turn green.
Mission 1: Your Agent's First Upload
Objective: Give your agent the ability to store its "memories" on Swarm.
  1. Your Task: Give your AI agent the following prompt (you can copy-paste it directly):
    Imagine an AI is a new student at Óbuda University. Write a one-paragraph story about its first day on the BĂ©csi Ășt campus and upload it to Swarm as simple text without topic.
  2. The Result: The agent will use the upload_text tool and return a JSON object containing a Swarm hash (called "reference"). It will look something like this:
    
{
"reference": "a1b2c3d4e5f6...",
"url": "https://api.gateway.ethswarm.org/bytes/a1b2c3d4e5f6...",
"message": "Data successfully uploaded to Swarm"
}
  3. Submit for Points: Copy the reference hash and submit it to the Leaderboard Portal at swarmai.bbw2025.buzz
    • Click Leaderboard (in the header).
    • Click Submit (in the header).
    • On the “Mission 1” tab enter the Swarm hash you copied from your AI too (in the previous step).
💡 Knowledge Unlock: Postage Stamps! Great job! Your agent just uploaded actual data to the decentralized web. This was possible because our workshop's Swarm Gateway has pre-paid for 'postage stamps'. Think of these like digital stamps that pay for your data to be stored and served on the Swarm network. In the real world, your agent would manage its own BZZ tokens to buy these stamps, making it truly autonomous!
Part 2: Advanced Missions
Mission 2: The Agent's Logbook
Objective: Create a persistent, agent-owned record on Swarm using its unique identity.
  1. Your Task: Take the reference hash you got from Mission 1 and use it in the following prompt:
    Create a university course log for me on Swarm. For the first entry, post the Swarm hash from our last mission. Use the topic bbw_2025
  2. The Result: The agent will use its private key to create a Swarm Feed and will return a JSON object with details about your new feed, including its topic.
  3. Submit for Points: Go to the Leaderboard Portaland submit your Feed Owner Address. This is the public address associated with your private key, which you can find on the workshop portal where you got your key. Our backend will automatically check your feed for the correct content and award you points!
Mission 3: The Living Memory
Objective: Update your agent's logbook, demonstrating how Swarm Feeds handle dynamic data.
  1. Your Task: Give your agent this simple command:
    Update my 'bbw_2025' feed with the following text: 'Phase 1 complete. The AI has successfully enrolled.'
  2. The Result: The agent will update the content of your feed.
  3. Automatic Reward: You don't need to submit anything! Our leaderboard is watching your feed and will automatically award you points once it detects the update.
💡 Knowledge Unlock: Swarm Feeds! You've just created a Swarm Feed! While the data you uploaded in Mission 1 is permanent and immutable (it can never be changed), a Feed acts like a dynamic pointer. The address of the Feed itself (made from your public key + a topic) never changes, but you—and only you—can use your private key to update what it points to. This is how you get mutable (dynamic) data on an immutable network, giving your agent a persistent memory it can update over time.
Part 3: Wrap-Up & Next Steps
Congratulations, Wrangler! You've successfully equipped your AI agent with the tools to store data, create a verifiable log, and operate on the decentralized web.
Leaderboard: Check out the final scores!
Badge of Honor: Everyone who completed all missions is now officially a "Swarm Agent Wrangler".
Thank you for participating, and welcome to the Swarm ecosystem!