docs/architecture/*.html.
Mykleos is a digital butler for the home: an AI assistant that lives on a family computer, speaks through the channels you already use (terminal, Telegram, later WhatsApp or voice), performs real actions (read files, run commands, query the web) but asks permission before doing anything serious.
The butler analogy is useful. A good butler:
/etc nor ~/.ssh);
Technically it is a Python ≥ 3.11 process running at /opt/myclaw/,
made of four layers (gateway, policy, sandbox, workspace/tool). Every AI
service (LLM, STT, TTS, embedding, speaker-ID) is consumed through an
abstract interface —
Mykleos is provider-agnostic by construction. In the author's specific
environment that interface is implemented by suprastructure, a
pre-existing sibling package; in another environment it could be implemented
by any equivalent adapter.
| Goal | What it means in practice |
|---|---|
| Local-first | Runs on the home PC. No data required to be in the cloud. Cloud is optional only (e.g. remote LLM providers, tunnels). |
| Safe by default | Bind on 127.0.0.1, autonomy Supervised, mandatory sandbox, forbidden paths, approval for risky actions. |
| Multi-channel | Same "mind", different interfaces: CLI, Telegram, later Signal, voice, web dashboard. |
| Open-ended | New tools and channels without rewriting the core: just conform to a Protocol. |
| Lock-in-free | The AI layer sits behind an abstract interface: swapping Claude for Ollama = one config line, no code change. In the author's environment the pattern is implemented by suprastructure. |
Both are excellent projects and have been the primary source of inspiration. Both, however, have traits that make them not-ready for home use on my PC:
| Project | Strengths | Limits for my case |
|---|---|---|
| openclaw TypeScript, Node 24+ |
Gateway-first design, 20+ channels, pluggable sandbox (Docker/SSH/OpenShell), skills registry, multi-agent routing | Node stack foreign to my other projects, more permissive defaults, cloud-oriented sandboxes |
| zeroclaw Rust 2024 |
Minimal footprint, autonomy levels, layered sandbox (Landlock+Bubblewrap), DM pairing, encrypted auth, 129+ security tests | Rust reintroduces a separate stack; rewrites from scratch the LLM/STT/TTS layer that I have already solved with an abstract interface and its own implementation (in my case suprastructure) |
The decision: take the best patterns from both (openclaw's gateway-first, zeroclaw's autonomy+pairing+layered-sandbox) and reimplement them in Python, where:
suprastructure) instead of rewriting it;Mykleos is an onion: the outside talks with the world, the inside executes. Each layer trusts only the layer further in, and grants less privilege the closer one gets to the centre.
A single FastAPI process exposing HTTP/WebSocket/SSE on 127.0.0.1:42618.
It receives messages from channels, manages sessions, dispatches webhooks, schedules cron jobs.
It is the sole point of contact with the world. It never directly executes sensitive commands.
The legality filter. Given an event ("user X wants to do Y"), it answers: allowed, denied, or allowed only after approval. It applies the autonomy level (see ch. 6), rate-limits, cost-caps (how much to spend on LLM calls per day), forbidden paths, and the state of pairing (ch. 7).
When policy says "yes", the action is still not executed free-hand.
For tools that touch filesystem or shell, we enter bubblewrap
(or systemd-run with hardening) with a profile picked from the
autonomy level. No direct subprocess.run, ever. Docker is a
future option for the strictest mode.
Inside the sandbox, the tool does its work: read a file from the workspace
(/opt/myclaw/workspace/), call an LLM via
registry.get(LLMProvider) on suprastructure, write a line in the
audit log. The workspace is the agent's "home": its markdown files of
personality and memory live there (ch. 8).
Let's follow a concrete example. You're in the garden, you write from Telegram: "tell me what's in tonight's log".
Mykleos never talks directly to Claude, OpenAI, Ollama or any other provider
of language models. It talks to an abstract interface
(typically a typing.Protocol) that the registry resolves at
runtime into a concrete implementation. The same holds for STT, TTS,
embedding, speaker ID. This is the pattern that makes Mykleos
provider-agnostic: whoever writes Mykleos doesn't need to know which
model will actually run, and whoever administers the environment can change
it with a single line of configuration.
In the diagram that follows, Mykleos is one consumer among others: a home agent for voice and smart-home control, further bots specialised on narrow domains. All share the same abstraction. None of them rewrites the AI layer: they use it.
suprastructure) stays interchangeable.The concrete benefit: a new model (e.g. Claude 4.7 when available) is configured once inside the interface implementation and all consumers inherit it simultaneously — Mykleos included. No code to rewrite, no deploy to coordinate.
Concept borrowed and adapted from zeroclaw. Every session runs at a declared autonomy level. The level determines how much Mykleos can do before having to ask for confirmation.
| Level | Default for | What it can do without asking | What requires approval |
|---|---|---|---|
| ReadOnly | First contacts, guests | Read files in the workspace, call LLM, run web search | Any write, any shell command, any outbound message |
| Supervised default |
Everyday use | The above + writes inside the workspace, allowlisted shell commands | Writes outside the workspace, non-allowlist commands, cost > threshold, outbound messages to third parties |
| Full | Explicit administrative sessions | Almost anything inside the home domain | Actions touching forbidden paths (/etc, ~/.ssh, ...): always denied, not approvable |
Full does not get through. Minimum list: /etc,
/root, ~/.ssh, ~/.aws,
~/.config/claude, /var/backups, other-project folders
in /opt/ distinct from myclaw.
The level can be raised temporarily via an explicit command
(myclaw session --level full --for 10m), logged and with automatic expiry.
A channel like Telegram is inherently multi-user: anyone who knows the bot's handle can write to it. Pairing is the mechanism that distinguishes a family member from a stranger.
Mykleos's "personality" is not in a Python file. It lives in
the workspace/, in five markdown files that Roberto can edit
whenever he wants without restarting. The idea comes from openclaw/zeroclaw
and is right on target: behavioural configuration is readable text, not a
data structure buried in code.
| File | Contents |
|---|---|
IDENTITY.md | Who the agent is: name, tone, preferred language, response style. E.g.: "you are a formal but terse butler, reply in English". |
USER.md | Who the primary user is: Roberto, habits, timezone, preferences, constraints. |
MEMORY.md | Long-term facts accumulated: "the router password is in Bitwarden", "the dog is called X", "calls Aunt every Sunday". |
AGENTS.md | Orchestration rules: when to delegate to a sub-agent, how channels map to autonomy levels. |
SOUL.md | High-level operating principles: "never lie about actions taken", "when in doubt, ask", "local-first". |
These files are injected into the system prompt at every LLM call (with proper caching so as not to burn tokens). Editing them is the primary way to "reprogram" Mykleos.
The audit log lives under workspace/.audit/ as append-only JSONL:
one row per tool call, with timestamp, sender, action, outcome, estimated cost.
suprastructure).
If a service is missing, it is added there, not here.The roadmap is deliberately small. One step at a time, with the microdesign document preceding the code.
| Phase | Goal | Gate |
|---|---|---|
| 0 (now) | This document + survival kit | Roberto approves the overall architecture |
| 1 | Repo skeleton + "hello world" gateway + CLI channel + sandboxed shell tool | gateway.html, channel.html, tool.html, sandbox.html written and approved |
| 2 | Policy engine + markdown workspace + audit log | policy.html, workspace.html, observability.html |
| 3 | Telegram channel + DM pairing | pairing.html + damage-containment plan |
| 4 | Persistent memory + provider failover via suprastructure | memory.html; suprastructure ≥ v0.4 if needed |
| 5+ | Voice channel (reuses supra's STT/TTS), optional tunnel, minimal web dashboard | evaluated case by case |
v1. Non-marginal
changes increment the number; the previous file stays accessible to trace
the evolution of architectural thinking.
Mykleos — Architecture: Introduction v1.0 — 2026-04-21
Inspired by openclaw and
zeroclaw, built on top of
suprastructure.