Keprix
CI and release automation run on GitHub Actions; their badges are hidden here while account-level
billing is unresolved (so a billing lock does not display as a code or test failure). The
workflows and test suite themselves are in .github/workflows/ and src/keprix/tests/ /
tests/ for direct inspection.
Keprix is a self-hosted AI agent OS, forked from Hermes Agent by Nous Research and significantly expanded. Community Edition is MIT-licensed. Run agents, tools, memory, a Command Center TUI, and a web workspace on your own infrastructure. A mutation engine can propose tool and skill changes with human approval. Channel Shield and a vault/credential layer protect inbound channels and secrets.
Quick Install
Stable installers and immutable terminal releases will appear at
keprixai.com/download only after their signatures,
checksums, SBOMs, and provenance are published.
Current source installation (Linux, macOS, WSL2):
curl -fsSL https://keprixai.com/install.sh | bash
This follows the development branch and is not an immutable stable release. Review
the script before running it. GitHub raw is the same file:
https://raw.githubusercontent.com/malike2356/keprix/main/scripts/install.sh.
Then:
source ~/.bashrc # or source ~/.zshrc
keprix # offers setup if no key, then starts chatting
keprix dashboard # local web workspace at http://127.0.0.1:9120/home
keprix dashboard install # keep the UI running after logout
Default home: ~/.keprix (code at ~/.keprix/keprix). Guide: docs/getting-started/install.md. Dashboard: docs/getting-started/dashboard.md.
Alternatives: pipx from git (see install.md); from a checkout, pipx install '.[tui]' --force (needs Python 3.11 or 3.12 - add --python python3.11 if your system's default python3 is older, e.g. Ubuntu 22.04's 3.10).
Optional Docker stack
Secondary path if you want Postgres, Redis, and a compose-fronted UI on this machine (not Contabo):
git clone https://github.com/malike2356/keprix.git
cd keprix
cp .env.example .env
# Set at least one LLM key
# On Linux, avoid a first-run permission error by matching the container to your host user:
mkdir -p ~/.keprix
echo "KEPRIX_UID=$(id -u)" >> .env
echo "KEPRIX_GID=$(id -g)" >> .env
docker compose -f docker/docker-compose.yml up -d --build
UI: http://localhost:3000; health: curl -s http://127.0.0.1:3333/api/health. Permission error instead? See Quickstart troubleshooting.
More: docs/getting-started/quickstart.md
What you get
| Component | Description |
|---|
| Workspace UI | Local Next.js: keprix dashboard / install at http://127.0.0.1:9120/home (optional Compose at :3000) |
| Command Center TUI | Textual terminal UI: chat, sessions, slash commands, tool cards, review |
| Agent runtime | FastAPI backend: LLM routing, tools, memory, MCP, cron |
| Mutation engine | Self-improvement loop for tools and skills (human approval) |
| Playbooks | Visual and YAML workflows with runs, approvals, schedules |
| Channel Shield | Inbound email/messaging protection, quarantine, policy hooks |
| Security | Vault, credential proxy, review gateway, ACLs, audit, Scout hooks |
| Deploy | Self-host on your machine (CLI dashboard or optional Docker Compose). keprixai.com is marketing only. |
Research notes
Channel Shield is a manipulation-defence surface for inbound messages: quarantine, policy hooks
and review before anything reaches the agent. The mutation engine is a study in gated
self-modification, where changes only apply after a second human approves them and the normal
test suite passes, with no auto-approve path.
Both are engineering substrates, not research outputs in themselves. Related detection and
adversarial-evaluation work is being scoped as a separate repository; nothing from that work
exists yet.
Repository layout
| Path | Purpose |
|---|
src/ | Python backend, CLI, agent runtime, API |
frontend/ | Next.js workspace and marketing shell |
docker/ | Images and Compose stack |
docs/ | Operator and developer docs (MkDocs) |
tests/ | Pytest suite |
config/ | Runtime YAML samples |
migrations/ | Alembic migrations |
domain-packs/ | Bundled domain skill packs |
scripts/ | Installers and ops helpers |
examples/ | Sample usage |
evals/ | Eval suites and fixtures |
mobile/ | Optional Android client |
sdk/, keprix_sdk/ | SDK surfaces |
packages/, apps/ | Workspace packages and app services |
keprix-proxy/ | Credential proxy |
deploy/ | Deploy helpers |
keprix-data/ and logs/ are local runtime data (gitignored); do not commit secrets. Internal planning trees such as 1st-plan/ stay on the workstation only and are not part of this public repository.
Documentation
Local MkDocs: bash scripts/serve-docs.sh then open http://127.0.0.1:8000
Related products (separate sites and licences): docs/community/related-projects.md
Lineage and Acknowledgments
Keprix is derived and forked from Hermes Agent by Nous Research, published under the MIT licence.
We give full credit and sincere gratitude to Nous Research and the Hermes Agent community for creating the foundational CLI runtime, interactive REPL, tool dispatch mechanism, bootstrap layer, and skill architecture that Keprix builds upon.
Building on top of the Hermes Agent core, Keprix introduces:
- A full-featured Next.js web workspace OS and REST API
- Multi-tenant isolation with PostgreSQL Row Level Security (RLS)
- Sandboxed Playbooks engine supporting visual and YAML workflows
- Channel Shield for inbound communication security and filtering
- Secure Document Vault with credential proxy and scoped exports
- Integrated Operator Command Center TUI and management portal
Full copyright and upstream MIT licence text are preserved in THIRD_PARTY_NOTICES.md. Broader open-source research acknowledgments are detailed in docs/community/acknowledgments.md.
Contributing
See CONTRIBUTING.md and docs/community/contributing.md.
Licence
MIT Community Edition. See LICENSE. Third-party notices and upstream Hermes Agent copyright: THIRD_PARTY_NOTICES.md. Self-host on your own infrastructure.
Authorship
Keprix Community Edition is maintained by Laud Paul Gablah (@malike2356),
founder of Verlox Ltd (keprixai.com).
Keprix is a derivative work. The CLI runtime, REPL, tool dispatch, bootstrap layer
and skill architecture come from Hermes Agent
by Nous Research. The human-approved self-modification engine, multi-tenant
isolation, credential vault and Channel Shield are Verlox additions.
See THIRD_PARTY_NOTICES.md for upstream attribution, and
docs/architecture/contribution-summary.md
for what was added, where the evidence lives, and how to verify it.
Contact
Verlox Ltd: [email protected]
