Dario Gabriel Lipicar
9c3d023062
The shell held the host's objects: MainContainer owned MainUIBackend, took a
LogosAPI* and a QtLogosCore*, and connected to backend signals by concrete
type. Nothing stopped it minting identities or reading the token store.
Three headers in app/interfaces/, on the include path both targets share, so
there is exactly one copy and source drift is impossible:
* IShellHost -- 8 operations the shell may perform
* IShellObserver -- 5 notifications the host may deliver
* IShellView -- how the host builds and tears down the shell
Only QObject*, QWidget* and Qt value types cross. MainContainer holds one
IShellHost* and nothing else; QML reaches the backend as an opaque QObject*
via backendObject(), resolved through the metaobject, so no host C++ type has
to be nameable by the shell.
Ownership inverts: Window owns MainUIBackend, ShellHostAdapter and
MainShellView; the shell borrows. Teardown stops being a consequence of
construction order and becomes a stated contract:
1. beginShutdown() unmounts in-process UI plugin widgets WHILE the shell's
tree is intact -- they are docked inside it
2. destroyShell() detaches the observer, then deletes the shell
3. the backend goes, tearing down Package -> UIPlugin -> Core
4. main() destroys the core facade
Every observer forward is null-guarded: PluginLoader dispatches through
QTimer::singleShot(0, ...) and a 30s ViewModuleHost timeout, so a callback can
land after teardown starts, and QPointer cannot help -- IShellObserver is not
a QObject. UIPluginManager's plugin-widget maps become QPointer for the
mirror-image reason: those widgets are docked inside the shell, so its Qt
parent can destroy them without going through unloadUiModule.
IComponent is untouched and still serves the third-party legacy widget
plugins PluginLoader loads.
logos-basecamp
Download
Prebuilt binaries for Linux (AppImage) and macOS (DMG):
- Stable release — latest release
- Latest RC / development build — all releases
Release candidates are marked as pre-release, so /releases/latest skips them. If the stable release is significantly older than the RCs on the releases page, you probably want an RC.
How to Build
Using Nix (Recommended)
Local Build
The local build produces a standard Nix derivation whose dependencies live in /nix/store. It is the fastest way to iterate during development but is not portable — it only runs on the machine that built it.
nix run .
# or: nix build '.#app' && ./result/bin/LogosBasecamp
Local builds require local .lgx packages, generated with:
nix bundle --bundler github:logos-co/nix-bundle-lgx github:your-user/your-module#lib
Portable Builds
Portable builds are fully self-contained — no /nix/store references at runtime. They work with portable .lgx packages. That is, releases from logos-modules, downloads from the Package Manager UI, or generated with:
nix bundle --bundler github:logos-co/nix-bundle-lgx#portable github:your-user/your-module#lib
| Output | Platform | Format |
|---|---|---|
bin-bundle-dir |
Linux, macOS | Flat directory with bin/ and lib/ |
bin-appimage |
Linux | Single-file .AppImage executable |
bin-macos-app |
macOS | .app bundle (ad-hoc signed, unsigned for distribution) |
Self-contained directory bundle (all platforms)
nix run .#bin-bundle-dir
# or: nix build '.#bin-bundle-dir' && ./result/bin/LogosBasecamp
Linux AppImage (Linux only)
nix build '.#bin-appimage'
./result/logos-basecamp.AppImage
MacOS App bundle (macOS only)
nix build '.#bin-macos-app'
open result/LogosBasecamp.app
Parallel Instances (--user-dir)
--user-dir <path> (or -u) sets the base directory so multiple Basecamp instances can run side-by-side with isolated plugins/, modules/, module_data/, and logs/. The path is used verbatim.
# Two instances with isolated state
./result/bin/LogosBasecamp --user-dir /tmp/basecamp-a &
./result/bin/LogosBasecamp --user-dir /tmp/basecamp-b &
Equivalent to setting the LOGOS_USER_DIR env var.
Inter-module access enforcement (--access-policy)
Default: off. Without this flag, any loaded module may call any other — unchanged behaviour.
--access-policy enforce turns on deny-by-default: a module may only call
the modules it declares as dependencies in its metadata.json, and any other
call is refused before it can proceed.
./result/bin/LogosBasecamp --access-policy enforce
The startup log states which side it landed on, so a policy that failed to arm is visible rather than silently permissive:
Installing inter-module access policy: {"version":1,"mode":"enforce","restrictions":{}}
Inter-module access enforcement is ON (mode=enforce): deny-by-default — ...
and a refusal names both modules, so a denial never presents as a mysteriously empty result:
[capability_module] access policy denies 'caller_module' -> 'target_module'
Known limitation — read before enabling. UI plugins (
ui_qml) load out-of-process and are not tracked as dependents in the core module registry, so the derived allow-list never contains them and their calls to their own backend module get denied (e.g.accounts_ui -> accounts_module). That is why this is off by default. Until the derivation accounts forui_qmlcallers, name them explicitly with a policy document.
--access-policy also accepts a path to a JSON policy file, or inline JSON,
where a restrictions entry replaces the derived allow-list for that
target:
./result/bin/LogosBasecamp --access-policy ./policy.json
./result/bin/LogosBasecamp --access-policy \
'{"version":1,"mode":"enforce","restrictions":{"accounts_module":{"allowedCallers":["accounts_ui"]}}}'
mode is the switch — only "enforce" activates gating, and enforce is
shorthand for exactly {"version":1,"mode":"enforce","restrictions":{}}. An
unreadable file or malformed JSON aborts startup rather than booting wide open.
Equivalent to setting the LOGOS_ACCESS_POLICY env var (the flag wins), which
is the way in for a launch with no argv — a double-clicked bundle or a desktop
entry. The same flag and spellings work on the logoscore CLI.
Development Shell
nix develop
Note: In zsh, quote the target (e.g., '.#app') to prevent glob expansion.
If you don't have flakes enabled globally:
nix build --extra-experimental-features 'nix-command flakes'
Nix Organization
The nix build system is organized into modular files in the /nix directory:
nix/default.nix- Common configuration shared by every derivationnix/app.nix- The application build (the UI shell compiles into it)
Modules
Blockchain
The Blockchain App lets you run your own blockchain node.
The app currently supports:
- Joining the Logos Testnet
- Participating in consensus (chain-following and proposing blocks)
- Making and receiving transfers
You can run the Blockchain App through the Logos Basecamp, or standalone by building and running the app from source, instructions here.
LEZ Wallet
The Logos Execution Zone Wallet App lets you interact with the Logos Execution Zone (LEZ). It is currently limited to basic account operations. This showcases both private and public execution through RISCV emulation and ZK Proofs.
The wallet currently supports:
- Initializing private/public accounts
- Inspecting private/public account balances
- Public to Public transfers
- Private to Private transfers
You can run the LEZ Wallet through Logos Basecamp, or standalone by building and running from source, see instructions here.
Storage
The Logos Storage App allows you to publish, download, and share files with other Logos users. You can run it both in standalone mode, or as part of the main Logos Basecamp.
Sharing files requires direct connection across nodes, so you will need to set up your router to allow NAT traversal either via UPnP, or manual port forwarding. The app will help you figure out if your NAT traversal is working with a reachability check.
Check the app's README file for more information on how to build, run, and troubleshoot it.
Chat
The Logos Chat App lets you send and receive private 1:1 messages, where messages are transferred over Logos Delivery, the decentralised transport layer. You can run it both in standalone mode, or as part of the main Logos Basecamp.
In the current testnet demo, the app supports:
- Creating and sharing your intro bundle (a contact identifier others can use to reach you)
- Starting private conversations by pasting a counterparty's intro bundle
- Sending and receiving messages in real time
To start a conversation, share your bundle with another user (via the "Share Bundle" button), and paste theirs into the new conversation dialog.
Check the app's README for instructions on how to build and run it in standalone mode.
Mix Demo Chat
You can use the Mix Demo Chat app to send anonymous chat messages over the mixnet. This demonstrates two core primitives working end-to-end:
- Decentralised discovery with capability filtering
- Anonymous message routing over the mixnet
Your chat client will first discover the necessary addresses and keys for a pool of mix nodes (using the capability discovery API) and then proceed to route every published message through this libp2p mix overlay network.
You can run Mix Demo Chat inside the Logos Basecamp. On loading, the UI will show the following:
- Status is shown as Ready
- LP Peer count increasing over time before stabilising
- Mix peer count increasing over time before stabilising
- Warning message
Waiting for network peers...disappears once 3 mix nodes are discovered
Once the warning message disappears, you can send messages, which will be receivable by others running the app.
Sent messages appear in the Messages section of the UI once they have been successfully delivered over the mix layer.
Mix Demo Chat can also be run as a standalone app. To do so, or for more information, refer to the module repo and instructions here.
Testing
Smoke Test
Validates the app starts without QML errors or crashes:
nix build .#smoke-test -L
cat result/smoke-test.log
UI Integration Tests
End-to-end tests that open apps, click buttons, and verify visible text using the QML Inspector.
Run via Nix (fully hermetic, suitable for CI — no Node.js or npm required):
nix build .#integration-test -L
cat result/integration-test.log
Run with Node.js (requires Node.js and a built app):
# Build the app and test framework (one-time):
nix build
nix build .#logos-qt-mcp -o result-mcp
# Run headless (launches the app, runs tests, kills the app):
node tests/ui-tests.mjs --ci ./result/bin/LogosBasecamp
# Or run against an already-running app:
node tests/ui-tests.mjs
# Run a subset:
node tests/ui-tests.mjs modules
Tests are defined in tests/ui-tests.mjs using the test framework from logos-qt-mcp. See the logos-qt-mcp README for the full test API.
AI Agent Interaction (MCP)
An MCP server allows AI assistants (Claude, etc.) to interact with a running instance of the app — inspecting the UI, clicking elements, reading properties, and taking screenshots.
Build the logos-qt-mcp package (one-time, includes the MCP server, test framework, and Qt plugin):
nix build .#logos-qt-mcp -o result-mcp
The .mcp.json in this repo is pre-configured to use the MCP server from result-mcp/mcp-server/. Start the app (inspector is enabled by default in debug/dev builds), and the agent can use tools like qml_find_and_click, qml_screenshot, qml_list_interactive, etc. See the logos-qt-mcp README for the full list of available tools.
Requirements
Build Tools
- CMake (3.16 or later)
- Ninja build system
- pkg-config
Dependencies
- Qt6 (qtbase)
- Qt6 Widgets (included in qtbase)
- Qt6 Remote Objects (qtremoteobjects)
- logos-liblogos
- logos-cpp-sdk (for header generation)
- logos-capability-module
- logos-package-manager
- zstd
- krb5
- abseil-cpp
Disclaimer
This repository forms part of an experimental development environment and is not intended for production use.
See the Logos Core repository for additional information about the experimental development environment: https://github.com/logos-co/logos-liblogos