Keystone Documentation

Keystone can be adopted in two ways:

• Keystone OS for full-machine ownership, including encrypted storage, services, users, and optional desktop tooling
• The Keystone terminal module for a portable developer environment on an existing macOS, Linux, or NixOS system

Most users should think in terms of a keystone-config repository. That repo is where you declare machines, users, enabled modules, and deployment settings.

Choose your path

Keystone OS

Choose Keystone OS when you want Keystone to manage the machine itself.

Use this path for:

• Servers
• Workstations
• Laptops
• Fresh NixOS installs
• Existing NixOS systems you want to reconfigure around Keystone modules

What you get:

• Disk layout and installation flow
• Secure Boot and TPM support
• ZFS-based storage defaults
• User management
• Optional desktop environment
• The Keystone terminal environment included for users who enable it

Start here:

• ISO Generation
• Keystone OS install
• OS module reference

Keystone terminal module

Choose the Keystone terminal module when you want the Keystone developer experience without replacing your operating system.

Use this path for:

• macOS
• Existing Linux distributions
• Existing NixOS machines
• Remote development boxes
• Thin clients

What you get:

• Zsh, Helix, Zellij, Git, and core CLI tooling
• Reproducible development environments
• A consistent terminal workflow across machines

Start here:

• Install the terminal environment
• Terminal module overview

Core concept: keystone-config

keystone-config is the repo that captures your Keystone setup. It is your flake, your machine definitions, and your configuration history.

Create a new config repo from the Keystone template:

nix flake new -t github:ncrmro/keystone keystone-config
cd keystone-config

This template gives you:

• flake.nix with Keystone and Home Manager wired in
• configuration.nix with the main Keystone options scaffolded
• hardware.nix for machine-specific hardware settings
• README.md with the post-scaffold checklist

Once created, edit the generated files, search for TODO:, and choose whether that repo will drive:

• A full Keystone OS machine
• A desktop-enabled Keystone OS machine
• A smaller terminal-first setup that still reuses Keystone modules

Recommended decisions

If you are new to Keystone

Start with one machine and one admin user in keystone-config.

Recommended first decision:

• Use Keystone OS if you are provisioning a new server, workstation, or laptop
• Use the terminal module if you want Keystone’s CLI environment on a machine you already manage another way

If you want the fastest safe first deployment

Use the template, keep the default single-machine structure, and work through:

1. ISO Generation
2. Keystone OS install
3. Terminal module overview

If you are iterating or contributing

Keep development workflows separate from initial setup:

• Developer workflow
• Thin client workflow
• Testing procedures
• VM testing

Quick Links

• Project Roadmap - Development milestones and future plans
• GitHub Repository - Source code and issue tracking
• Create keystone-config - Scaffold a new Keystone configuration repo

Documentation Overview

Getting Started

• Keystone Config - Start from a minimal flake that mirrors the Keystone template
• Installing Keystone TUI - Install the Keystone terminal environment on macOS, Linux, or NixOS
• Terminal Module - Understand the portable terminal experience
• ISO Generation - Build Keystone installation media
• Keystone OS install - Install Keystone OS on target hardware

Module Documentation

• OS
  • Server
  • User Management
  • Build Platforms
• Terminal
  • Terminal Module
  • Shell Tools
  • Functions
  • TUIs
  • SSH Agent
  • Projects and pz
  • Developer workflow
  • Thin client workflow
• Desktop
  • Desktop
  • Walker
  • Fingerprint Unlock
  • Monitors
  • Windows VM
  • Desktop Keybindings
  • Screen Recording
  • Presentations
  • Waybar Configuration
• Services
  • Remote Building and Caching
  • External Mail Providers
  • Keystone Managed Services
• Hardware
  • Hardware Keys
  • TPM Enrollment
  • NAS

Projects

• Projects and pz - Project hubs, pz, Zellij sessions, and desktop project switching
• Notes - Shared notebook model for project hubs, reports, and durable context

Agents

• Agents - Human-side agent workflows, agentctl, and starting feature work
• OS Agents - Provisioning, task loop architecture, and platform source discovery

Development

• Developer workflow - Daily terminal workflow on a full machine
• Thin client workflow - Remote or lightweight client workflow
• Testing Procedures - Validation and regression workflow
• VM Testing - Iterate on Keystone in virtual machines

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.