> For the complete documentation index, see [llms.txt](https://docs.holons.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.holons.io/getting-started/run-your-first-holon.md). # Run Your First Holon This is the practical companion to [What is a Holon?](/getting-started/what-is-a-holon.md). It walks through the actual steps of getting a holon running—people coordinating in chat, contributions being recognized, work being scored, federation to other holons, and AI agents able to participate via MCP. You can stop after any step. Each one produces a working holon at a different level of capability. ## Level 0 — A chat group The simplest holon is a group of people coordinating in one channel. No tools required. 1. Create a Telegram (or any chat) group. 2. Write the holon's **purpose** in the channel description: one sentence about what the holon is for. 3. Invite the people who will participate. That's it. You have a holon: it has a [membrane](/getting-started/glossary.md#membrane) (the group), [shared DNA](/getting-started/glossary.md#shared-dna) (the purpose), and members. Everything that follows just makes it more legible. ## Level 1 — Add HolonsBot This step turns informal coordination into structured, attributable records. 1. Follow [Setting up your holonic organization](/daos/setting-up-your-holonic-organization.md) to deploy [HolonsBot](/software/holonsbot.md) (or its modern incarnation `@holons/telegram-ui`) into the group. 2. Add the bot as an administrator. 3. Try the basic verbs: | Verb | Example | | ------------------------- | ----------------------------------------------- | | Create a task | `/task water the seedlings` | | Recognize a contribution | `/appreciate @laura for hosting tonight's call` | | Make an offer | `/offer yoga sessions on Tuesday mornings` | | Make a request | `/request someone to drive the truck on Friday` | | See where everyone stands | `/status` | The holon now has a [task log](/software/tasks.md), an [appreciation record](/software/scoring.md), and an open board of needs and offers. It is a [Managed Holon](/software/holons-types-flavor/managed-holon.md). ## Level 2 — Define what counts The next step is to make the holon's **values** explicit. This is what shapes what gets recognized. 1. Add **chromosomes** describing your values, tools, and practices — through the bot or directly via the [DNA domain](/software/dna.md). 2. Build a **DNA sequence** from the chromosomes that most define this holon (max 20). 3. Tune the [**value equation weights**](/software/scoring.md) so contributions you care about (hours, appreciations, completed quests, specific currencies) carry the right relative weight. A nature-stewardship holon might weight outcomes (`completed`) and appreciations heavily, with hours secondary. A research collective might weight hours and currencies (paid grants) higher. There is no universal right answer—the equation **is** the culture. ## Level 3 — Federate A single holon is useful. A federation is regenerative. 1. Identify one or two sibling holons—other groups doing related work. 2. Use the bot's `/federate` command (or call the [federation domain](/software/federation.md) directly) to declare the trust relationship. 3. Once federated, you can [publish](/software/federation.md) quests, offers, requests, or appreciations across the boundary. Holons that share a [settings hex](/software/federation.md#settings-hex-integration) can also be discovered by anyone subscribing to that cell. Federation is bilateral and revocable. Each side keeps its own DNA, value equation, and rules; only the items each chooses to publish cross the membrane. ## Level 4 — Open to AI agents This is what makes the difference between a holon that AI watches and a holon AI **participates in**. ### Option A — In-process Claude loop Use [`@holons/ai-ui`](/software/ai-ui.md) when you want intelligence **embedded in** the holon's own infrastructure (a bot handler, a cron job, a webhook): ```bash export ANTHROPIC_API_KEY=sk-… holons-ai "Summarize this week's open quests in the garden holon" ``` The agent runs as the holon, with the actor identity you've configured (`HOLONS_ACTOR_*` env vars). ### Option B — MCP server for external agents Use [`@holons/mcp-ui`](/software/mcp-server.md) when you want **external** clients (Claude Desktop, IDE plugins, custom agents) to participate: ```bash # stdio mode — typical for Claude Desktop node packages/mcp-ui/dist/index.js # SSE on HTTP — when the server must be reachable over the network node packages/mcp-ui/dist/index.js --port 3200 ``` Configure the MCP client with the appropriate `HOLONS_PEER`, `HOLONS_APP`, and `HOLONS_ACTOR_*` env vars. The agent now sees \~100 tools spanning every core domain. A holon at this level has: * Humans coordinating through chat. * Programmatic records (tasks, expenses, appreciations) that drive scoring. * A clear identity (DNA) and culture (value equation). * Trust relationships with sibling holons (federation). * AI agents able to read, write, and act as first-class members. ## A worked example: the community garden Three people start a neighborhood garden: 1. **Level 0.** They create a Telegram group, write "we steward this land and grow food for the block" in the description, and invite five neighbors. 2. **Level 1.** They add HolonsBot. The first week they log 11 tasks (`/task plant herbs`, `/task fix the gate hinge`) and exchange 23 appreciations. 3. **Level 2.** They add chromosomes — `regenerative practice`, `mutual aid`, `gardening tools`, `consent-based decisions`. They tune their value equation: `completed: 3` (outcomes matter more than starting things), `appreciations: 2` (peer recognition is core), `hours: 1`. The bot's `/status` now reflects what they actually value. 4. **Level 3.** Three nearby gardens federate with them. A surplus harvest gets `/published` to the federation; a request for help with a workshop reaches all four gardens at once. A bioregional aggregator subscribed to the settings-hex picks up the workshop and lists it on a regional board. 5. **Level 4.** They configure the MCP server with the garden's identity and connect Claude. Now a member can ask Claude, in a sentence, to "schedule a watering rotation for the next two weeks based on the weather forecast and people's stated availability." Claude reads the holon's state, calls the appropriate MCP tools, and the rotation appears as a set of recurring quests—every member can see, accept, or reassign them. ## Where to go from here * **Tune the system.** Read [Scoring](/software/scoring.md) and adjust your value equation; read [DNA](/software/dna.md) and refine your chromosomes. * **Compose flavors.** Layer a [Splitter Holon](/software/holons-types-flavor/splitter-holon.md) on top to route incoming funds; declare [Zones](/software/holons-types-flavor/zoned-holon.md) for differentiated participation. * **Connect deeper.** Read [Funding Flow](/getting-started/funding-flow.md) for the protocol-level mechanics of multi-currency, threshold-based distribution. * **Glossary.** Anything unfamiliar lives in the [Glossary](/getting-started/glossary.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.holons.io/getting-started/run-your-first-holon.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.