A security-hardened personal AI agent platform. Secure by Design and by Default — not as configuration, but as architecture.
| Status | Early implementation. Trust-plane crates, the maknaed daemon, per-request authorization (RBAC composed with a mandatory (MAC) ceiling operand, enforced), and local-plane enrollment are landing; pre-MVP. |
| Domain | https://maknae.io (registered, Cloudflare; holding page pending) |
| Core spec | design/knowledge-lifecycle-contract.md — read this first |
| Agent guidance | AGENTS.md — core principles and conventions for AI agents and tools (CLAUDE.md is a symlink to it) |
| Maintainer | Alex Ackerman (@darkhonor); AI agents (Claude, Codex) contribute under blind review, never merge |
| License | Apache-2.0 |
Maknae is a personal AI agent platform built around a security kernel. Where existing agent platforms treat security as configuration sprinkled on top of a capable runtime, Maknae inverts the relationship: a small, auditable trust plane mediates every action, every piece of knowledge, and every network flow, with the agent runtime treated as untrusted by design. Deny by default, everywhere, always.
The platform's defining feature is a governed learning loop: the agent is permitted to learn — generating skills from experience and ingesting documents into its own local Knowledge Lake when tasked work reveals a gap — but no acquired knowledge is trusted until the kernel admits it. Content from a source the operator registered in a signed authority map is validated and admitted at its authority position; content from anywhere else waits for review and informs nothing until then; what the agent generates itself climbs a provenance-stamped promotion ladder. The operator may also ingest a document directly, at the position they attest. The agent fills its knowledge base itself, from operator-authorized sources only, learning the "official way" to do things as defined by that map.
Supported platforms are Linux (amd64 and arm64) and macOS on Apple Silicon (arm64); there are no x86 macOS builds. Maknae installs as host packages (rpm, deb and the macOS .pkg) running as system services under dedicated accounts: maknaed as _maknae and the Egress Daemon (maknae-egress) as _maknae-egress, under systemd on Linux and launchd on macOS, drawn in the Service Architecture. Containers appear only as tool invocations, and those are planned vision: the Agent Daemon that would spawn them and the tool containers themselves have no ADR and no code yet. A containerized deployment (a Compose stack or Kubernetes) is a possible future option, designed in design/container-architecture.md. The host-package path protects its bootstrap credential at rest: on Linux it is sealed to a hardware root of trust, TPM 2.0 or a vTPM, so a Raspberry Pi with no TPM isn't a host-package target; on macOS it is a System-keychain item that only the Developer ID-signed daemon can read (on a real install the signed daemon reads it, and a read through /usr/bin/security (not on the item's ACL), in a console session, of the daemon's item as the operator and of the Egress Daemon's item as _maknae, raised an administrator-approval dialog each time; denied, it exited 128 (errSecUserCanceled, -128): an administrator can approve a read in a console session, and root can decrypt it off the host (inferred)), under the System keychain's root-held key rather than hardware (ADR-0018 decision 6); a future Kubernetes deployment would use platform identity (Vault Kubernetes auth) with no secret at rest and need no HRoT (ADR-0018). Single-binary is not a goal; small-and-auditable is.
Recommended production host. For the strongest posture — a bootstrap credential sealed to a TPM, SELinux, and systemd confinement — run Maknae on Rocky Linux 10 or RHEL 10 with TPM 2.0; choose that host when a deployment must meet a hardware-root-of-trust or mandatory-access-control requirement. macOS is supported with the posture deltas stated in packaging/macos/README.md and packaging/isolation-contract.md.
The north-star deployment is a classified, multinational, air-gapped enclave — partner operators as attribute-bearing subjects, a full Bell-LaPadula classification lattice with releasability categories, and every model endpoint local and accredited. That is not a special mode: it is the same kernel with a richer lattice and a stricter authority map, which a homelab runs with a trivial lattice at zero ceremony.
Maknae began as a survey project — fork-and-merge the best of two open-source agent platforms the operator runs in production:
- OpenClaw (running as HobiBot) — the layered-control school: decoupled model layer, core runtime, explicit skills, atomic tool abstractions. Discipline.
- Hermes Agent (Nous Research; running as TaeBot) — the learning-first school: self-improving skills from experience, decoupled memory, multi-channel gateways, native MCP, scheduling. Growth.
The fork premise died on inspection: both projects make architectural decisions that treat security as configuration, not structure. Retrofitting a deny-by-default trust plane into either codebase would fight its architecture forever. So Maknae is a greenfield platform with two reference implementations — it adopts Hermes' learning-loop and scheduling concepts and OpenClaw's explicit-control discipline, governed by a kernel neither of them has.
Three ideas set it apart from both upstreams:
- Policy-bound authorization. Every consequential action transits a single deny-by-default reference monitor. The default in-repo model is Role-Based Access Control (RBAC), composed with a mandatory (MAC) classification-ceiling operand — degenerate ABAC over the declared system's level order (ADR-0022; US = the four-level EO 13526 order, AUS = the six-rung PSPF ladder): content at or below the declared
core.handling.ceilingflows, content marked above it is refused, unmarked content is the system's lowest level (USUNCLASSIFIED, AUSUNOFFICIAL), on every content request (#148; nothing stamps a marking yet — #229 makes higher markings expressible); where the optional external classification (DCS, Data Classification Service: a private library the default build does not need) library is present, it enriches decisions to full Attribute-Based Access Control (ABAC) — role plus clearance, classification, and releasability. Mandatory controls (classification, SELinux) always take precedence over discretionary grants: an administrative role never buys read-up, and even the kernel is constrained (ADR-0020). - Zero Trust. Every decision evaluates the tuple (subject, action, resource, context). Freshly retrieved content is an untrusted principal until it is promoted — it can inform a decision but never authorize one.
- Unified knowledge lifecycle. Skills (procedural), lake documents (declarative), and memories (episodic/semantic) all flow through one authority-tiered promotion pipeline. See the contract.
Three planes — this describes the design; see Status & roadmap below for what has actually landed:
- Interaction plane — gateway, web UI, and a scheduler with scoped task identities. Accepts work; trusts nothing.
- Trust plane — the kernel, and the only trusted code. It holds the reference monitor (
maknaedis the sole policy decision point), the deny-by-default access policy, the signed and tiered skill registry, and the append-only audit log. Nothing touches anything without transiting it. - Runtime plane — the agent runtime with the gated learning loop, plus integrations acting as policy information points. Does the work, under constraint.
The kernel is 100% Rust (ADR-0002): memory-safety guidance makes the language choice a citable control, the contract's invariants encode into the type system, and the operator's Microkosmos webserver supplies the in-house FIPS 140-3 Rust precedent. Authorization is evaluated behind a policy-agnostic, versioned seam (crates/maknae-security) with pluggable maknae-authz-* backends (ADR-0004): a bundled RBAC/allowlist default (maknae-authz-basic) composed with a mandatory (MAC) classification-ceiling operand (a ceiling over the declared system's level order (ADR-0022; US = the four-level EO 13526 order, AUS = the six-rung PSPF ladder), in-repo — #148, corrected 2026-09-06), an optional classification backend via the external DCS library, and room for third parties to bring their own engine — Cedar is now one optional backend, not the engine (ADR-0003, superseded). The capability-grant grammar operators write policy against — the discretionary layer, decided by RBAC (ADR-0020) — is enforced per request as of #77: every request renders a real PDP verdict, and the shipped deny list (~/.ssh and friends) actually denies on the daemon-mediated Read path (crates/maknae-config carries the grammar; crates/maknae-authz-basic decides). Every other container picks the language best suited to its job — see design/container-architecture.md — with rigor calibrated to the layer, affordable precisely because the kernel, not the runtime's good behavior, is the control.
Modular by contract, where it earns its keep. Where a component has a genuine substitution axis — the authorization engine is the worked example — Maknae prefers a stable, versioned contract with swappable implementations behind it over a hard-wired one. A hard-wired choice forces a solution that ages out and becomes both lock-in and attack surface; a narrow, versioned seam lets the implementation change, or a third party bring their own, without touching the core. Applied where it earns its keep, not everywhere.
Test-driven development applies to every container in every language; because segments are AI-implemented, the suite doubles as mutation-proofing, and coverage rigor scales with how security-critical the code is (ADR-0016). Architecture diagrams live in design/diagrams/.
Maknae (막내) is the generic Korean kinship word for the youngest member of any group. It was chosen deliberately:
- The lore. HobiBot and TaeBot are the hyungs (older brothers); Maknae is the youngest — born last, raised by the older two, inheriting the best of both. A "golden maknae" is a youngest member who is inexplicably good at everything, which is precisely this project's best-of-both-worlds thesis.
- The IP posture. The word is generic Korean vocabulary — not coined, not trademarked, no corporate association. A 2026-07 namespace survey confirmed it clean on PyPI, npm, and crates.io. The personal meaning is real; the public name is unclaimable.
- The convention. In the operator's ecosystem, hosts get World of Warcraft names, agent personas get their own names, and standalone projects get culturally-generic names. Maknae the platform hosts personas; the personas are runtime configuration, never the product identity.
Maknae is pre-MVP but no longer paper: the trust-plane crates, the maknaed daemon (with STIG-baselined packaging and SELinux/AppArmor profiles), per-request RBAC authorization with an enforced deny list (#77) and a non-removable classification-ceiling operand (#148/#154), and the local-plane enrollment model (ADR-0018) are landing. The phased plan:
- Governance baseline — Knowledge Lifecycle Contract review; authority basis aligned to the Knowledge Lake's authority-line model; the open questions resolved with rationale.
- Authorization seam & default backend — build the bundled RBAC default (
maknae-authz-basic) behind the versioned, policy-agnosticmaknae-securityseam and wire per-request evaluation (ADR-0004). Optionalmaknae-authz-*backends — classification via the external DCS library, or Cedar — are scoped as follow-on, not the core engine decision. - Trust-plane kernel — the reference monitor (
maknaedas the sole PDP) composing the authorization backends deny-overrides, and audit events (underway). - Runtime loop — Maknae acts as an agent. Root authorizes the model providers; each user chooses theirs from that set and keeps their own key in Vault under their own login; the Egress Daemon makes the call.
read_fileandwrite_fileare performed by your own client, each decided and recorded by the kernel before it happens. (Accepted on Rocky 10, 2026-09-27, and on macOS 2026-09-29, withtransport.read_timeout_ms: 60000(#413). Set it up: docs/first-provider.md.) - Lake integration — a portable lake instance, authority map v0.1 (egress allowlist plus authority basis), and the intake routes with review hold.
- Learning loop MVP — gap detection → registered fetch → validated admission (or review hold) → out-of-band consolidation ("dreaming") → gated promotion of self-generated knowledge.
- Gateway and web UI — an onboarding wizard (CLI and web) for authority configuration, and the scheduler with scoped task identities.
- Persona layer — the hyungs move in.
Two capabilities are first-class by design from the start (design intent, not yet shipped). Model-layer registration is dual-mode: OAuth subscription authentication and OpenAI-compatible endpoint registration (including self-hosted and air-gapped inference), with provider endpoints as kernel-allowlisted egress destinations and credentials delivered via Vault, never plaintext. Task-class model routing is a policy decision that weighs task cost, content sensitivity (in classified deployments, no-egress or classified context may reach only endpoints authorized for it), and subject attributes — the model endpoint is itself an attribute-gated resource carrying operator-signed labels (jurisdiction, sanctioning authority, handling ceiling), so an operator's attributes constrain which models may serve them and data sovereignty holds even for unattended, scheduled work. One persona per instance is the proven deployment pattern (multi-persona is deferred behind a feature gate), while a single agent serving multiple operators — each with their own attribute set — is designed in from the start.
.
├── AGENTS.md # contributor/agent guidance (CLAUDE.md → symlink)
├── Cargo.toml # Rust workspace
├── coverage-tiers.toml # risk-tiered coverage contract (ADR-0016)
├── deny.toml # supply-chain gate (cargo-deny)
├── bins/ # maknae (CLI), maknaed (daemon), maknae-spifc (SPIF compiler)
├── crates/ # trust-plane kernel, authz, audit, secure I/O, SPIF, MCP, vault, subject-context
├── ci/gates/ # fail-closed CI gates (coverage, negative-control, isolation-contract)
├── packaging/ # STIG-baselined deb / rpm / macos / oci packaging
├── deploy/ # deployment assets (Vault PKI, …)
├── docs/ # configuration, operator runbook, first-provider walkthrough, verification walkthrough
└── design/
├── knowledge-lifecycle-contract.md # the governance spec — read first
├── container-architecture.md # possible future containerized deployment (Compose / Kubernetes)
├── reference-implementation-autopsy.md
├── adr/ # architecture decision records
├── references/ # external-framework assessments
└── diagrams/
Rust 1.98.1 (the pinned toolchain; rustup installs it from rust-toolchain.toml) on Linux (amd64/arm64) or macOS on Apple Silicon.
cargo build --locked --workspace
cargo test --locked --workspace--locked is not optional here: CI refuses a manifest that drifts from Cargo.lock, and so should your shell.
By default the pre-push hook runs the coverage-tier and drift gates; formatting and clippy are checks CONTRIBUTING.md asks you to run yourself before pushing, and CI enforces for everyone. Opt in with MAKNAE_PRE_PUSH_LINUX_CLIPPY=1 and the hook additionally runs the Linux clippy lane in a container. (Corrected 2026-09-11: this said the pre-push gate covers "formatting, clippy as errors". Before this change ci/hooks/pre-push ran neither and had never contained a clippy invocation in any revision — a reader who enabled the hook on the strength of this sentence got neither check. It still runs no fmt, and runs clippy only on that opt-in.) Packaging for deb, rpm and macOS lives under packaging/.
CONTRIBUTING.md— development workflow, the pre-push gate, commit conventions, and the DCO sign-off.SECURITY.md— how to report a vulnerability. Please do not open a public issue for one.CODE_OF_CONDUCT.md.
Start with AGENTS.md — the direction Maknae's AI agents and tools follow, and a useful reference for human contributors. It carries the core principles and conventions and points at the load-bearing detail. In short: deny-by-default applies to designs too (absence of a permission is a denial); nothing self-promotes (no content, skill, or config gains authority without transiting the promotion pipeline); verify through the fail-closed gates in ci/gates/; and record decisions as ADRs. The Knowledge Lifecycle Contract invariants are acceptance criteria — violating one is a wrong answer even if the code works.
Maknae's two reference implementations are the operator's production agents — study their architecture, inherit their concepts, not their trust models:
- OpenClaw — https://github.com/openclaw/openclaw (layered-control reference)
- Hermes Agent — https://github.com/NousResearch/hermes-agent (learning-first reference)
It also builds on the maintainer's prior work (private repositories): the Knowledge Lake (authority-tiered, deterministic markdown retrieval — the architecture Maknae's lake is a portable instance of), Claude Memory (the shared memory system with out-of-band "dreaming" consolidation), the Security MCP Server (a live OAuth 2.1 + ABAC gateway — prior art for the kernel's decision point), and Microkosmos (the FIPS 140-3 Rust precedent). Assessments of comparable third-party platforms live in design/references/: the DeepSeek Harness (a TypeScript agent harness), Agent Deck (a Rust multi-agent TUI orchestrator), Omarchy (an agent-first Linux desktop, the host-side counterpart to Maknae's kernel-side answer), and the Jarvis-class field survey (twelve personal-agent systems on one eight-axis template, with deep dives on OpenJarvis and IronClaw). How each risk in the OWASP Top 10 for LLM Applications 2025 maps onto Maknae's built, planned and candidate controls is set out layer by layer, with assessments of the guard tools examined along the way (Meta Prompt Guard and Llama Guard, NVIDIA NeMo Guardrails, Protect AI LLM Guard, and a survey of 20+ other tools and three architectural defenses).
Apache License, Version 2.0 — see LICENSE and NOTICE. Third-party crate attributions are in THIRD-PARTY-NOTICES.md. Contributions are accepted under the same license with a Developer Certificate of Origin sign-off; see CONTRIBUTING.md.
The youngest one, raised by the best of both. 막내 화이팅.
The CLI runs with your user ID and OS permissions. Users and admins share the filesystem policy in authz.yaml; the admin role grants no additional filesystem access. The shipped policy allows reads within your home and writes within ~/projects/**, with sensitive-path denies. Operators can change those path grants independently of management roles.
printf 'hello\n' | maknae write ~/projects/demo.txt
maknae mkdir --parents ~/projects/demo/src
maknae read ~/projects/demo.txt
maknae delete ~/projects/demo.txt
maknae delete --recursive ~/projects/demowrite consumes raw stdin bytes within the configured prompt budget. The kernel decides the write and records its intent; the CLI then replaces existing content, or creates an absent file exclusively, under your own credentials, and reports the outcome. A collision never silently overwrites another file. read prints a file's raw bytes: the kernel decides the read and records its intent, and the CLI reads the file under your own credentials, reports the byte count, and prints the bytes once that report is recorded. Delete without --recursive removes a file, symlink, or empty directory. Recursive delete requires authority over the entire subtree and never follows symlinks.
Reads, replacement, creation, deletion, and mkdir are authorized attempts performed by the CLI, where the OS checks your credentials at each syscall. Their audit results are explicitly client-reported. A timeout or lost connection may leave partial or unreported effects; inspect the filesystem before issuing another command. The supported CLI stops when an acknowledgment is missing and does not retry uncertain work.