Building on Logos Core: The Modular Architecture and Package Manager
Every application on the Logos stack follows the same developer journey. Source code becomes a module. A module becomes a package. A package loads into the runtime. The runtime becomes an application.
The Logos Core team has been building modules and apps on this platform, and we’ve learned a lot from that process. This article walks through the developer journey we’ve refined — from scaffolding your first module to distributing it through the Logos package manager. You should see not just where the platform is, but where it’s going — and the better developer experience waiting for you when you start building.
If you’ve read “Understanding the Logos Tech Stack: An Operating System for Sovereignty”, you already understand the why. This is the how.
The Pipeline
Logos Core’s architecture is a five-stage pipeline. Every module — whether it’s the wallet, the chat client, or something you build tomorrow — passes through these same stages:
Source Files → Logos Module Builder → Logos Module → Logos Package (LGX) → LibLogos Core → Logos App
Or, more concisely: Build → Define → Distribute → Execute.
Each stage has its own tooling, its own CLI commands, and its own concerns. Together they form a complete developer workflow — from writing code to having users install your module through the Logos Basecamp package manager. Let’s walk through each one.
Stage 1: Build — The Logos Module Builder
The first problem we faced when building modules was the sheer number of configuration files needed. It got messy: lots of makefiles, Nix files, things that had to happen under the hood. Worse, this led to inconsistency between projects — some had code generation, others didn’t, and different conventions emerged across the board. Things wouldn’t work as expected, and onboarding new contributors meant explaining a different setup for each module.
The Logos Module Builder eliminates this problem. It’s a Nix flake template that scaffolds the build system, dependency management, and configuration for a new module. One command:
nix flake init -t github:logos-co/logos-module-builderThis generates a project with a module.yaml configuration file and a minimal flake.nix. The key insight is what it eliminates. Before the module builder, creating a new module meant maintaining nix/default.nix, nix/include.nix, nix/lib.nix, a sprawling CMakeLists.txt, and a complex Nix flake — hundreds of lines of build configuration before you wrote a single line of application logic.
The module builder reduced this dramatically. CMakeLists.txt diffs show +10/-286 — 276 lines removed. Flake.nix diffs show +6/-64 — 58 lines removed. What remains is the minimum:
mkLogosModule {
src = ./.;
configFile = ./module.yaml;
}Define your source files and your dependencies. The builder handles the rest.
This approach has multiple advantages beyond simplicity. When we update the underlying technology, everything should just work for the module developer — no changes required on their end. We can push improvements to all modules at once. Nix commands are now standardized across every module in the ecosystem — nix build, nix develop, nix flake check — so the workflow for building the wallet module is identical to building the chat module or any third-party module.
There are also AI-assisted skills available to create new modules from scratch and to update existing modules to the new builder format. The update skill is particularly handy — it does a solid job of migrating older modules automatically.
This is configuration debt reduction as a design principle. Less boilerplate means fewer places for builds to break, faster onboarding for new contributors, and a consistent developer experience across the entire module catalog.
Stage 2: Define — The Logos Module
Once your code compiles, the Logos Module Builder produces a Logos Module — the fundamental unit of the Logos Core ecosystem.
The Abstraction Layer
There’s a common misunderstanding that we’re “doing Qt plugins” or “using Qt” — that’s not the right way to think about it. What you’re creating is a Logos Module that just happens, at the moment, to be implemented using Qt under the hood. This might or might not be the case in the future.
From your perspective as a developer, you’re creating a Logos Module. You shouldn’t care about the underlying implementation. You care that you’re building a Logos Module with particular properties that works in a particular way within Logos Core.
We introduced the Logos Module library to make this abstraction explicit. By wrapping the plugin system behind the Logos Module API, the underlying technology can be swapped out without rewriting module logic. Your module code talks to the Logos Module interface, not to Qt directly. If the plugin system changes tomorrow, your module doesn’t.
The Logos Module Library provides the programmatic interface:
// Load a module from disk
auto plugin = LogosModule::loadFromPath(pluginPath);
// Introspect available methods
auto methods = LogosModule::getMethodsAsJson(plugin);The lm CLI
Every module ships with metadata that the lm CLI tool can inspect:
# View module metadata
$ lm metadata
name: logos-chat-module
version: 0.3.1
description: Chat module for Logos Core
author: Logos Collective
type: service
dependencies: [logos-messaging-module, logos-capability-module]
# List available methods
$ lm methods
sendMessage(channel: string, content: string) -> MessageResult
getHistory(channel: string, limit: int) -> Message[]
onChatMessage -> Event<Message>This is more than a convenience tool — it’s the foundation for tooling, debugging, and the package manager’s dependency resolution. Every module is self-describing.
One API Pattern Across Three Languages
Logos Core provides SDKs for JavaScript, Nim, and C++. All three follow the same calling convention:
logos.<module_name>.<method>(params)
In practice:
// JavaScript
const result = await logos.chat.sendMessage("general", "hello");
logos.chat.onChatMessage((msg) => console.log(msg));# Nim
let result = logos.chat.sendMessage("general", "hello")
logos.chat.on("chatMessage", proc(msg: Message) = echo msg)// C++
auto result = logos->chat.sendMessage("general", "hello");
logos->chat.on("chatMessage", [](const Message& msg) {
std::cout << msg << std::endl;
});The naming convention shifts slightly per language — JavaScript uses onChatMessage while Nim and C++ use on("chatMessage") — but the conceptual model is identical. Learn one SDK and you understand all three.
To demonstrate this in practice: in a recent demo, the team took the chat module and used it in an Electron app, in a terminal chat application, and inside the Logos Basecamp app — completely different technologies, yet the base module was the same. This is what we aim for: take our technology and make it easy for anyone to use on any platform without worrying about the underlying details.
This matters because Logos Core modules are written in different languages: the blockchain module is in Nim, UI modules use C++ with QML, and developer tooling increasingly targets JavaScript. A unified API pattern means these modules compose naturally regardless of implementation language.
Stage 3: Distribute — The Logos Package (LGX)
A compiled Logos Module needs to reach users on different operating systems and architectures. This is the job of the LGX package format and its associated tooling.
The LGX Format
An .lgx file is a tar.gz archive with a defined structure:
my-module.lgx
├── manifest.json
└── variants/
├── linux-amd64/
│ └── libmy-module.so
├── linux-arm64/
│ └── libmy-module.so
├── darwin-amd64/
│ └── libmy-module.dylib
└── darwin-arm64/
└── libmy-module.dylib
The manifest.json contains module metadata — name, version, description, dependencies — and the variants/ directory holds per-platform binaries. One package, every supported platform.
The lgx CLI
The lgx tool creates and manipulates LGX packages:
# Create a new package
$ lgx create --name my-module --version 0.1.0
# Add a platform variant
$ lgx add --variant linux-amd64 --file build/libmy-module.so
# Add another variant
$ lgx add --variant darwin-arm64 --file build/libmy-module.dylib
# Extract a package
$ lgx extract my-module.lgxlgx exists as both a library and a CLI, so CI pipelines can automate package creation programmatically.
The lgpm Package Manager
End users and developers interact with modules through lgpm — the Logos package manager:
# List installed modules
$ lgpm list
# Search for available modules
$ lgpm search chat
logos-chat-module 0.3.1 Chat module for Logos Core
logos-chat-ui 0.2.0 Chat UI for Logos App
logos-irc-module 0.1.0 IRC bridge module
# Install a module
$ lgpm install logos-chat-moduleModules are organized into categories — Accounts, Blockchain, Chat, Management, Protocol, Security, Wallet — reflecting the breadth of the ecosystem. The package manager fetches packages from GitHub releases, making distribution as straightforward as cutting a release on a GitHub repository.
Multi-Platform CI
The distribution story is backed by CI actions that build portable libraries and binaries across operating systems and architectures. Static library linking ensures that modules built with Nix are portable outside of Nix environments — a critical requirement for adoption, since not every user or deployment target has a Nix installation. CI portability checks validate that packages work correctly on target platforms before release.
Stage 4: Execute — LibLogos Core
With modules built, defined, and packaged, LibLogos Core is the runtime that brings them to life. It is the kernel described in the “Logos as an Operating System” article — the microkernel that loads modules, manages their lifecycles, and provides the IPC infrastructure for them to communicate.
Process Isolation and Security
Each module runs in an isolated manner for security and stability. Currently modules run in separate processes, but the architecture is designed for more: it’s quite possible that in the future, modules will run in containers or even on different machines — and yet they can all talk to each other through the same API.
A crash in the chat module doesn’t take down the wallet. A misbehaving third-party module can’t corrupt the blockchain node. The Core is a hub — it starts module processes, monitors their health, and restarts them if they fail. This is the same philosophy as a microkernel operating system: just as a crashed printer driver on a microkernel OS doesn’t bring down the filesystem, a crashed Logos module doesn’t bring down the Core.
Inter-Process Communication and Permissions
Modules communicate through built-in IPC channels managed by LibLogos Core. The architecture might look like everything only talks to Logos Core, but modules can actually talk to each other directly. The Core ensures they have permissions to communicate with the right modules — you might authorize a module to talk to your wallet, but you don’t necessarily want all modules to have that access.
The Core also manages sessions, so modules can run on different machines while the developer uses the same API regardless. The routing of messages is completely abstracted — as a developer, you don’t need to know where a module is running to communicate with it.
The IPC architecture also enables dependency auto-loading. When a module declares a dependency on another module, LibLogos automatically loads the dependency first. Install the chat UI module, and LibLogos will pull in the chat module, the Logos Messaging module, and any other dependencies declared in the chain.
Three Ways to Execute
There are three ways to run modules on LibLogos Core:
1. Dedicated App with SDK — Build your own application using the SDK in whatever language you prefer. Your app loads LibLogos as a library, starts the modules it needs, and uses the logos.<module>.<method> API to interact with them. This is how you’d build a custom Logos-powered application.
2. Headless Mode (logoscore CLI) — Run the full LibLogos Core runtime without any graphical interface:
# Run with a specific module directory
$ logoscore -m /path/to/modules
# Load specific modules
$ logoscore --load-modules logos-blockchain-module,logos-messaging-module
# Execute a method directly
$ logoscore -c "logos.blockchain.getLatestBlock()"This enables server-side deployments — validators, infrastructure nodes, CI test environments — where modules run as background services. Pass a folder of modules, choose which ones to load, and the runtime automatically handles dependencies (loading the chat module will automatically load the wallet module if it’s a dependency). It’s the daemon mode for Logos: the same runtime, the same modules, the same IPC, without a window.
3. Logos Basecamp (Super App) — The default end-user application that provides a graphical interface to the entire module ecosystem. More on this below.
What’s Running Today: The Module Ecosystem
The pipeline isn’t theoretical. Thirteen modules are built, packaged, and distributed through it today:
| Module | Type | Description |
|---|---|---|
| logos-accounts-module | Service | Account management and identity |
| logos-accounts-ui | UI | Accounts interface (QML) |
| logos-blockchain-module | Service | Blockchain node with event emission |
| logos-blockchain-ui | UI | Blockchain node manager (QML) |
| logos-capability-module | Service | Capability discovery protocol |
| logos-chat-module | Service | Encrypted messaging |
| logos-chat-ui | UI | Chat interface |
| logos-irc-module | Service | IRC bridge |
| logos-package-manager | Management | Package installation and resolution |
| logos-storage-module | Service | Decentralized file storage |
| logos-messaging-module | Protocol | Logos Messaging relay protocol |
| logos-wallet-module | Service | Wallet and token management |
| logos-wallet-ui | UI | Wallet interface (QML) |
The UI modules — wallet, accounts, blockchain — have been reworked in QML, a declarative language for building fluid, modern interfaces. These aren’t placeholder mockups; they’re production UI code backed by real module APIs.
The blockchain module integrates directly with the Logos blockchain, emitting events that other modules can subscribe to through the IPC layer. Nix-based C++ code generation automates the binding between blockchain data types and the module’s C++ interface, reducing the manual glue code that typically makes blockchain integrations brittle.
The demo chat application — built on the chat module, the Logos Messaging module, and the capability discovery protocol — is now being dogfooded internally by the Logos team. It’s real usage over a real network, not a conference demo. Mix protocol integration provides network-level privacy for message routing, and capability discovery (fully spec-compliant with the extended-kad-disco specification) lets nodes find each other without centralized infrastructure.
A unified design system provides shared UI components and typography across all modules, ensuring visual consistency as the module catalog grows.
Logos Basecamp: The Interface to It All
“Logos is the parallel society. Logos Basecamp is the interface to it.” — Jarrad Hope
Everything described above — the build pipeline, the module abstraction, the package format, the runtime — converges in Logos Basecamp, currently in ALPHA v0.1.3.
Basecamp is the user-facing application powered by the LibLogos backend. It provides a graphical package manager for browsing, installing, and managing Logos Core modules. Open the package manager, browse the catalog, install the modules you want, and Basecamp handles dependency resolution, platform-appropriate binary selection, and module lifecycle management.
The app displays each loaded module with real-time CPU and memory usage — you can see the Logos Messaging module running as a full node, the wallet module idle, and the chat module processing messages. This isn’t a mockup; it’s the actual runtime exposing its internals.
Five proof-of-concept applications ship with Basecamp today:
- Package Manager — browse and install modules from the catalog
- Wallet — manage tokens and view balances (using the Go Wallet SDK)
- Chat — encrypted messaging over the Logos network
- Blockchain Node Manager — run and monitor a blockchain node
- Storage — decentralized file storage and retrieval
Each application is composed entirely of Logos Core modules running through LibLogos. The wallet app is the wallet module plus the wallet UI module plus the accounts module. The chat app is the chat module plus the Logos Messaging module plus the chat UI module. Basecamp doesn’t implement these features — it loads the modules that do.
This is the modular architecture made tangible. Users don’t need to understand Nix, LGX packages, or IPC channels. They see applications. Developers see a distribution platform for their modules.
Getting Started
The fastest path from zero to a running module:
1. Scaffold
nix flake init -t github:logos-co/logos-module-builder2. Configure — edit module.yaml with your module’s metadata and dependencies.
3. Build
nix build4. Inspect
lm metadata
lm methods5. Package
lgx create --name my-module --version 0.1.0
lgx add --variant linux-amd64 --file result/lib/libmy-module.so6. Test locally
logoscore -m ./result --load-modules my-module7. Distribute — push the .lgx to a GitHub release, and the package manager picks it up.
The module builder handles the build complexity. The LGX format handles cross-platform distribution. LibLogos handles runtime orchestration. You focus on what your module does.
What Comes Next
Logos Core is in active development. The module builder templates are stabilizing, the package manager is fetching from GitHub releases, and Basecamp provides the first end-user interface to the ecosystem. The blockchain module integration, the QML UI rework, and the demo chat app dogfooding all represent the platform moving from proof-of-concept to production readiness.
The architecture is designed to scale with the ecosystem. New modules plug into the same pipeline. New languages get SDKs that follow the same logos.<module>.<method> pattern. New platforms get CI targets and LGX variants. The pipeline stays the same; what flows through it grows.
For developers building on Logos, the path is clear: scaffold a module, define its API, package it for distribution, and let LibLogos handle the rest. The operating system for sovereignty now has a developer experience to match.
This article is the hands-on developer companion to “Understanding the Logos Tech Stack: An Operating System for Sovereignty”. That piece explains the architecture’s purpose — modularity, privacy, and user sovereignty. This one shows you how to build on it.