⚙️ How It Works
Every extension lives in its own directory with a manifest that declares what it needs and what it provides. The loader scans these manifests on boot, validates dependencies, and wires routes, tools, jobs, and models into the land automatically.
Extensions only receive the services they declare. If an extension says it needs the User model and the energy service, that's all it gets. It cannot access the orchestrator, LLM routing, or any other service it didn't ask for. This is the permission boundary.
📂 Think of It Like an OS
In a traditional OS, you install programs that extend what the system can do. A fresh OS has a file manager and a terminal. You install a browser, a text editor, a music player. Each program registers its file types, adds menu entries, and integrates with the system.
TreeOS works the same way. A fresh land has nodes, notes, values, and AI chat. You install extensions for scripts, understanding runs, billing, Solana wallets, blog posts. Each extension registers its routes, models, energy costs, and CLI commands.
📋 The Manifest
Every extension has a manifest.js that declares its contract:
export default {
name: "understanding",
version: "1.0.0",
description: "Bottom-up tree compression with LLM summarization",
// Required: won't load without these
needs: {
services: ["llm", "session", "aiChat", "orchestrator"],
models: ["Node", "Contribution"],
},
// Optional: works without these (no-op stubs injected)
optional: {
services: ["energy"],
},
provides: {
models: { UnderstandingRun: "./models/run.js" },
routes: "./routes.js",
tools: "./tools.js",
jobs: "./job.js",
energyActions: { understanding: { cost: 1, unit: "per-node" } },
sessionTypes: { UNDERSTANDING: "understanding-orchestrate" },
cli: [
{ command: "understand", description: "Start understanding run" },
],
},
};
The needs field lists required dependencies. If they're missing, the extension won't load. The optional field lists services that enhance the extension but aren't required. If the host land doesn't have energy, the extension still works. Energy calls become silent no-ops.
🔄 Lifecycle
Search
Find extensions in the registry
treeos ext search blog
→
Install
Pull from registry, write files to land
treeos ext install blog
→
Active
Loaded on boot, routes and tools available
treeos ext list
Disable
Skip on next boot, files stay
treeos ext disable blog
→
Enable
Load again on next boot
treeos ext enable blog
→
Uninstall
Delete directory, data stays in database
treeos ext uninstall blog
📦 Built-in Extensions
TreeOS ships with these extensions. They're all optional. A minimal land runs with just the core protocol.
understanding
Bottom-up tree compression with LLM summarization
scripts
Sandboxed JavaScript on nodes with value/goal mutation
prestige
Node versioning system with archived history
schedules
Date scheduling and calendar views for nodes
energy
Daily energy budget with tier-based limits
billing
Stripe subscription tiers and energy purchases
raw-ideas
Unstructured capture with auto-placement pipeline
dreams
Daily background maintenance: cleanup, drain, understand
blog
Land-level blog for posts and updates
book
Export tree notes as shareable documents
solana
On-chain wallets and token operations per node
api-keys
User-generated API keys for programmatic access
user-llm
Custom LLM connections and per-user model routing
user-queries
Notes, tags, contributions, chats, notifications
deleted-revive
Soft delete with branch recovery
visibility
Public/private tree toggle and share tokens
transaction-policy
Per-tree trade approval rules
html-rendering
Server-rendered HTML pages via ?html parameter
🚀 Publishing
Anyone running a land can publish extensions to the registry. Other lands can search, install, and use them. The registry stores extension files and manifests. No npm account needed, no build step. Just write a manifest.js and index.js, and publish.
treeos ext publish my-extension
Published extensions appear in the registry. Other land operators can find them with treeos ext search and install with treeos ext install.
🔧 Building an Extension
An extension is a directory with at minimum two files:
manifest.js . declares needs, provides, version
index.js . exports init(core) function
routes.js . optional, Express router factory
core.js . optional, business logic
model.js . optional, Mongoose schema
The init(core) function receives a scoped services bundle and returns what the loader needs to wire up:
export async function init(core) {
return {
router: createRouter(core),
models: { MyModel },
tools: getTools(core),
exports: { myFunction },
};
}
🌐 API Endpoints
GET/api/v1/land/extensionsList all loaded extensions with status
GET/api/v1/land/extensions/:nameGet manifest details for an extension
POST/api/v1/land/extensions/installInstall extension from registry data
POST/api/v1/land/extensions/:name/publishPublish local extension to registry
POST/api/v1/land/extensions/:name/disableDisable extension (restart to apply)
POST/api/v1/land/extensions/:name/enableRe-enable disabled extension
POST/api/v1/land/extensions/:name/uninstallRemove extension directory (data kept)