FAQ

Common questions about Holons, answered in one place

Quick answers to questions that come up often. Each one links to the deeper page where appropriate.

Concepts

What is a holon?

A holon is something that is both a whole and a part. In the Holons protocol it is a self-governing unit (a family, team, co-op, neighborhood, region) that can also participate in larger structures. See What is a Holon?.

What's the difference between Holons, THEOS, and Holonic Funding?

• THEOS (The Holonic Earth Operating System) — the broader open-source proposal at theos.io. Describes a holonic, peer-to-peer social coordination protocol aligned with planetary boundaries.

• Holons — colloquial shorthand for the protocol THEOS describes, and for working implementations of it (such as the Liminal Village software ecosystem documented in these docs).

• Holonic Funding — the economic/financial layer of the implementation (splitters, threshold buckets, value equations, federation).

See the glossary's naming section and THEOS.

What's the difference between HoloSphere and HolonsBot?

• HoloSphere is the substrate — a JavaScript library for distributed, H3-indexed data.

• HolonsBot is one of several interfaces people use to operate holons (Telegram). It writes to HoloSphere through @holons/core.

Other interfaces include the web dashboard, the CLI, the AI agent, and the MCP server.

Does a holon have to be geographic?

No. H3 indexing is the default addressing scheme because most early use cases were place-based (gardens, hubs, bioregions), but a holon can be any string ID. A holon for a virtual community, a distributed project, or a dataset is just as valid.

What's a "value equation"?

A formula chosen by each holon that turns contributions (hours, appreciations, completed quests, currency balances) into scores. Different weights produce different cultures—what a holon weights is what its members get recognized for. See Scoring.

Setup

Where do I start?

If you want the philosophy first: Introduction → What is a Holon?.

If you want to get running: Run Your First Holon.

If you're a developer: The Shared Core.

What do I need to run a holon?

For a basic Managed Holon on Telegram: a Telegram group, HolonsBot, and 10 minutes. See Setting up your holonic organization.

For a federated holon with the web dashboard, AI agent, and MCP server: the Harvest monorepo, Node ≥20, pnpm ≥10, and a Gun relay (the default https://gun.holons.io/gun works out of the box).

Do I need to host my own Gun peer?

No. The default https://gun.holons.io/gun works. Hosting your own peer makes sense once you have data sovereignty or latency requirements that the default doesn't meet.

What's the difference between @holons/ai-ui and @holons/mcp-ui?

Both expose @holons/core to AI agents, but at different layers:

• @holons/ai-ui runs an in-process Claude tool-use loop. Best when the holon itself wants to interpret natural-language input.

• @holons/mcp-ui is an out-of-process MCP server. Best when external clients (Claude Desktop, IDE plugins, third-party agents) should drive the holon.

A holon can run both. See AI UI and MCP Server.

Architecture

Why is there one core and many UIs?

So that "compute user score," "create a task," or "publish to federation" means the exact same thing regardless of how a user reached the system. Without a shared core, every UI re-implements the logic, the implementations drift, and the same user sees different results in different surfaces.

See The Shared Core.

How do new domains get added?

Create packages/core/src/<domain>/index.ts, export the public surface, write a vitest spec. The subpath wildcard in package.json makes @holons/core/<domain> importable instantly. Then optionally add packages/mcp-ui/src/tools/<domain>.ts to expose it as MCP tools.

See The Shared Core.

Why H3 indexing?

Hierarchical hexagons give the system constant-time parent/child/neighbor lookups, stable IDs across clients computing the same coordinate, and natural aggregation patterns. Aggregating "all readings for this region" is a child-cell traversal rather than a custom regional schema.

See HoloSphere.

Why GunDB?

Decentralized, real-time, peer-to-peer, offline-tolerant. Trades transactional consistency for autonomy and resilience. The Holons domains are designed to work with eventual consistency rather than against it.

See HoloSphere.

Operations

What does "federation" actually mean in practice?

Two holons declare a trust relationship. Once federated, items one holon publishes (quests, offers, appreciations, expenses) become visible to the other under the rules each holon set for itself. Neither side gives up its autonomy—each keeps its own DNA, value equation, and storage namespace.

See Federation for the implementation and the glossary for the concept.

Can a holon belong to many federations?

Yes. The federation graph is a normal graph, not a tree—every holon can declare as many trust relationships as it wants. Items get published to specific targets (all, partner, hex) so a holon can choose where each publish lands.

How does a holon recognize contributions from a federated partner?

Through appreciation data flowing across the federation, weighted into the local value equation. The Appreciative Holon pattern is the canonical answer; the Scoring domain handles the math.

Can I run a holon without HolonsBot?

Yes. HolonsBot is one interface; the web dashboard, CLI, AI UI, and MCP server all do the same things. A holon could run with only the MCP server and a Claude agent, with no chat surface at all.

AI integration

Can a Claude agent be a member of a holon?

Yes—via either @holons/ai-ui (in-process) or @holons/mcp-ui (out-of-process). The agent resolves to an actor identity (HOLONS_ACTOR_*), and every action it takes is attributed to that identity in HoloSphere. Scoring, federation, and audit all treat it like any other member.

What tools can the MCP server call?

Roughly 100 tools across 14 domains: tasks, council, scoring, REA-via-HoloSphere reads, DNA, library, expenses, calendar, users, federation, holosphere, checklists, shopping, settings, and commands. See MCP Server.

How do I keep an AI agent from acting on behalf of someone it shouldn't?

Identity-aware writes (canWriteToHolon in @holons/core/holosphere) check permissions at the substrate level. The MCP server's resolveActor picks up the identity from env vars; if those map to a member with restricted standing, the agent inherits those restrictions automatically.

Troubleshooting

"Write access denied" when publishing

The destination holon's ACL refused the write. The publish doesn't abort—it records the denial in the PublishOutcome.errors and continues with other destinations. To fix the denial itself, check the destination's federation settings.

See Federation: how permission denials surface.

"JavaScript heap out of memory" in the web dashboard

Large federated networks can exhaust the default Node.js memory limit. Bump it:

export NODE_OPTIONS="--max-old-space-size=4096"
pnpm dev

See Harvest: memory management.

The MCP server starts but Claude can't see any tools

Check that registerAllTools succeeded—each tool module is imported lazily, and a missing module is skipped silently. Look in stderr for "holons-mcp-ui running on stdio" (or "listening on port N (SSE)") to confirm the server is up; if it is but tools are empty, the build likely didn't include packages/mcp-ui/dist/tools/*.js. Re-run pnpm -F @holons/mcp-ui build.

Score changes aren't reflecting in the UI

The value equation is cached synchronously for instant access. If a weight changed but the UI is still showing the old score, the cache hasn't been refreshed—call preloadEquation(holonId) or subscribe via subscribeToEquationChanges().

See Scoring: subscriptions and caching.

I have another question

Open an issue in the relevant repo, or ask in the channel where your holon coordinates. If you find a recurring question worth adding here, edit this page and add it.