OpenLumara: a modular, token-frugal agent framework you run yourself

What OpenLumara is actually for

The README frames OpenLumara around two problems: system prompts that grow large enough to cost real money on hosted APIs, and agent frameworks that ship shell access and background scheduling as always-on defaults. The project's answer is a Python framework written from scratch, not derived from openclaw, in which the system prompt can reportedly be as small as roughly 4000 tokens under normal use. The maintainer states that the framework is local-first and pairs well with llamacpp and koboldcpp, which is where a small prompt matters least financially but most in terms of context budget on a modest machine.

The stated audience is narrower than the feature list suggests. The README calls out life management directly: todos, notes, morning routines, habit tracking, and it says the author uses it that way most of the time. It goes further and names executive dysfunction, including ADHD and autism, as a reason someone might find it useful. That is an unusual thing for a framework README to say, and it sets an expectation: this is a personal assistant you host, not an orchestration layer for a fleet of autonomous workers. Teams looking for multi-agent pipelines or a hosted control plane will not find that described here.

The module system is the whole architecture

Everything in OpenLumara that other frameworks treat as core is a module that can be switched off. The README lists shell access, memory, the scheduler, time-awareness, and token-awareness as modules. Turning all of them off leaves an empty system prompt and a direct line to the base model. Modules are toggled with the `/module` command or by editing the config file. There is also a `modules` module that lets the model toggle modules on your behalf, and it is disabled by default for security, which is the correct default for anything that lets a language model change its own capabilities.

The naming rule is mechanical and worth knowing before you write anything: a class named in CamelCase becomes snake_case in the config file and everywhere else. So `MyModule` is `my_module`. Channels follow the same convention. A channel subclasses `core.channel.Channel`, and the README's own example is `class Example(core.channel.Channel)`. That is the entire extension surface described in the material: a Python class with a few special methods, placed where the loader can find it. The README says a proper plugin downloading system is coming later, which means today you are copying files into the tree yourself.

Data flow: chat in, modules expand the prompt, backend answers

The flow visible in the README is straightforward. A channel receives a message. Channels listed as currently supported are WebUI, CLI, Telegram, Discord, and Matrix, with Matrix noted as having encryption support. The active modules contribute to the prompt: memory, scheduler, time-awareness, token-awareness, characters, and so on. The assembled context goes to whatever OpenAI API-compatible backend you configured, which can be a local server or a cloud provider. The reply comes back through the same channel.

Two commands expose that pipeline rather than hiding it. `/status` reports the current context window size in input tokens. `/context` shows exactly what is being sent. The README also says the model itself can see your token use, which is a design choice with a cost: it consumes prompt space to report prompt space. The memory module stores data in messagepack format, which the README describes as compact and fast. The character module is scoped per chat session, so a character active in the WebUI does not affect a Telegram session, and loading a chat that had a character active reloads it. That session scoping is the kind of detail that decides whether a feature is usable in practice, and it is stated explicitly here.

Getting it running

Installation is git-based, and the README is explicit about why: the update scripts depend on git. The command given is `git clone https://github.com/Rose22/openlumara`. Downloading the zip is offered as an option with the caveat that `update.sh` on Linux and `update.bat` on Windows will not work that way.

Once cloned, run `run.sh` on Linux or `run.bat` on Windows. The process prints a URL; you open it in a browser. Configuration happens in the WebUI settings panel, reached through the gear icon at the top. There you set up the API connection, press save, and start talking. Updates are `update.sh` or `update.bat`, run from the checkout.

That is the full documented setup path. There is no package on PyPI, no container image published by the project, no configuration file schema in the README beyond the note that module names map from class names. If you want to know which keys exist, you read the config file the project generates or the source. For a framework whose selling point is that you can turn pieces off, the absence of a documented key list is a real gap, and the README's own tip (ask the AI running on OpenLumara how to use it) is a workaround rather than documentation.

The sandboxed shell, and why it is off by default

The shell module is the most interesting security decision in the project. It runs inside a docker or podman container, and the README says you have fine-grained control over that container, including cutting it off from the internet and choosing which docker image to run. It is disabled by default. So is the `modules` module that lets the model toggle other modules.

Those two defaults tell you what the maintainer is worried about. An agent that can run shell commands and also rewrite its own module configuration is an agent that can grant itself capabilities. Keeping both off means a fresh install cannot execute anything or escalate on its own. The cost is that the default experience is much less capable than the feature list implies, and you will spend your first session in the settings panel and the config file enabling what you actually want.

Cutting the container off from the network is the setting that matters most if you enable shell access at all. The README presents it as an option you control, not a default, so a container with network access and a model that can be persuaded to fetch a URL is a combination you are choosing deliberately rather than inheriting.

Where it stops being the right tool

The honest limitation is maturity. The repository shows no releases, and the README describes a plugin downloading system as something coming later. That means every module you add is a file you wrote or copied, and every update is a git pull against a moving main branch. There is no version to pin, no changelog to read before upgrading, and no compatibility contract for the module interface beyond the CamelCase-to-snake_case rule.

The README also discloses that the project is AI-assisted. The core folder was hand-written, but the author states that non-core parts, including many channels, were mostly generated by AI and then manually audited and edited. That is a reasonable disclosure, and it is more than many projects offer, but it tells you where to look first if something behaves oddly: the channel implementations, not the core. If your use case depends on Matrix encryption or Discord behaviour, you are relying on code with a different provenance than the framework underneath it.

Finally, GPL-3.0. If you plan to embed OpenLumara in a product you distribute, the licence terms apply to that distribution. This is not legal advice, and the specific obligations depend on how you link and ship the code, so read the licence text and get proper advice if the answer matters commercially.

How it differs from the frameworks it is reacting to

The clearest comparison in the README is to openclaw, which OpenLumara explicitly is not based on, and whose cronjobs the scheduler is described as a from-scratch alternative to. The difference in approach is not the feature set, since both schedule tasks for the model. It is the default posture. In OpenLumara, scheduling, memory, shell access, and time-awareness are modules that start in a state you chose, and the system prompt only grows by what you enabled. The README's claim that you can turn everything off until the prompt is empty is the sharpest way to state that difference.

For character chat, the README positions the character module against Character.AI, Janitor AI, and SillyTavern. The mechanism that distinguishes it is prompt replacement rather than prompt addition: when a character is active, all other prompts are disabled and the system prompt is purely the character. That is a different design from layering a persona on top of a general assistant prompt, and it is why the session scoping matters. Whether it is better depends on whether you want the assistant's other capabilities available while in character. OpenLumara's answer is no, and it is a deliberate one.

Editorial conclusion

Adopt OpenLumara if you already run a local OpenAI-compatible backend such as llamacpp or koboldcpp, you care about how many tokens your system prompt burns, and you want to turn off shell access and the scheduler by default. Skip it if you need a stable release process, a plugin registry, or a framework with an established third-party module ecosystem, because none of those exist here yet. Before committing, read core/ and the module loader in the repository to see how config keys map to module names, confirm that your backend's model list is exposed through the OpenAI-compatible endpoint, and check whether the docker or podman sandbox image you intend to use is reachable if you plan to enable the shell module.

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Rose22/openlumara on GitHub