Keystone

Self-sovereign infrastructure platform with secure, encrypted NixOS deployments

---

Project maintained by ncrmro Hosted on GitHub Pages — Theme by mattgraham

Keystone Documentation

Welcome to the Keystone documentation. Keystone is a NixOS-based self-sovereign infrastructure platform that enables users to deploy secure, encrypted infrastructure on any hardware.

Quick Links

• Project Roadmap - Development milestones and future plans
• GitHub Repository - Source code and issue tracking
• Quick Start - Get up and running quickly

Documentation Overview

Getting Started

Installation & Deployment

• Installation Guide - Complete installation process from ISO generation to first boot
• ISO Generation - Building custom installation media
• Examples - Server and client deployment examples
• VM Testing - Virtual machine testing workflows
• Testing Procedures - Comprehensive testing guide

Security & Encryption

• TPM Enrollment - TPM2-based disk encryption setup
• Secure Boot Testing - Secure Boot configuration and testing
• User Management - User configuration and access control

Module Documentation

• Terminal (keystone.terminal) - Shell, editor, and development tools (Zsh, Helix, Zellij, etc.)
• Desktop (keystone.desktop) - Hyprland desktop environment
  • Screen Recording - GPU-accelerated screen recording with audio capture
• Agent Sandbox - Run AI agents in isolated MicroVM environments

Advanced Topics

• Build Platforms - Cross-platform build configuration
• Hardware NAS - Network Attached Storage setup

Quick Start

1. Build Installation ISO

# Clone the repository
git clone https://github.com/ncrmro/keystone.git
cd keystone

# Build ISO with your SSH key
./bin/build-iso --ssh-key ~/.ssh/id_ed25519.pub

2. Test in a VM (Optional)

# Quick VM test with automated build
./bin/build-vm terminal    # Terminal environment
./bin/build-vm desktop     # Full desktop environment

# Or use the full-stack VM testing
./bin/virtual-machine --name keystone-test-vm --start

3. Deploy to Hardware

# Boot target machine from ISO
# Get IP address from installer console

# Deploy from your development machine
nixos-anywhere --flake .#test-server root@<installer-ip>

4. Post-Installation

# SSH into deployed system
ssh root@<server-ip>

# Enroll TPM for automatic unlock
keystone-enroll-tpm

# Verify secure boot status
bootctl status

Architecture Overview

System Types

Servers

Always-on infrastructure providing:

• Network gateway and VPN services
• DNS with ad/tracker blocking
• Storage and backup services
• Media streaming
• Container hosting

Clients

Interactive systems featuring:

• Workstations - Always-on development machines with remote access
• Laptops - Portable devices with full desktop environments
• Hyprland Wayland compositor
• Terminal development environment
• Secure boot and full disk encryption

Security Features

• TPM2 Integration - Hardware-based key storage and attestation
• Full Disk Encryption - LUKS + ZFS native encryption
• Secure Boot - Lanzaboote with custom key enrollment
• Zero-Knowledge - All data encrypted before leaving devices

Key Technologies

• NixOS - Declarative, reproducible system configuration
• ZFS - Advanced filesystem with snapshots and compression
• Disko - Declarative disk partitioning
• Home Manager - User environment management
• SystemD - Service orchestration and boot management

Development Roadmap

Current Release: v0.0.1 (Alpha)

• ✅ Encrypted server with TPM2 unlock
• ✅ Secure Boot support
• ✅ ISO installer
• 🔧 Documentation and polish needed

Upcoming Releases

v0.0.2 - Developer Environment

• Terminal development via SSH
• Home-manager integration
• Cross-platform development

v0.0.3 - Workstation Desktop

• Hyprland compositor
• Remote desktop access
• Full application suite

v0.0.4 - Universal Development

• GitHub Codespaces support
• macOS compatibility
• Portable configurations

See the full Roadmap for detailed version plans and future features.

Contributing

We welcome contributions! Areas where help is particularly needed:

• Documentation improvements
• Testing and bug reports
• Security auditing
• Module development
• Platform support

Please see our GitHub repository for details on how to get involved.

Community & Support

• Issues - GitHub Issues
• Discussions - GitHub Discussions
• Security - Report security issues privately via GitHub Security Advisories

License

Keystone is open source software licensed under the MIT License.

---

This documentation is continuously updated. For the latest information, please check the GitHub repository.