Codegeist OS

Codegeist OS is the workspace for a NixOS-based personal desktop that integrates a catalog-selected local language model, the Codegeist CLI, and accelerator- backed local speech while keeping AI execution separate from the normal human user.

Purpose

The project defines an operating system in which AI-assisted actions are constrained by operating-system identity, policy, approval, and auditable system boundaries. Access to human data, credentials, devices, processes, networks, and privileged operations must be granted deliberately and remain revocable.

codegeist-llm owns logical language-model selection, training, provenance, evaluation, runtime-variant production, and release artifacts. codegeist owns the CLI and its native releases. This repository owns the single reviewed catalog that integrates those LLM variants with third-party speech variants and hardware profiles, plus their operating-system isolation, lifecycle, updates, rollback, and recovery.

Version 1 Target

The first integration milestone is intentionally narrow:

• NixOS with classic stable Nix interfaces, not experimental Nix Flakes.
• Separate x86_64 and aarch64 UEFI desktop images using GNOME.
• A model-free base VM and live ISO containing runtimes and reviewed catalog metadata but no LLM or speech-model payload.
• A broad hardware-profile contract for CPU and independently verified Intel, AMD, NVIDIA, and Qualcomm accelerators. The RTX A2000 12GB remains the first planned CUDA reference profile, not a measured or universal requirement.
• One approved logical language-model release with multiple cataloged variants for formats, quantizations, system architectures, backends, and resource envelopes.
• SafeTensors as the canonical training output and quantized GGUF as the OS runtime-variant format where appropriate.
• An offline local inference service that remains unavailable until a future installer or explicit test harness provides a verified catalog variant, and is reachable by the AI only through a bounded inference gateway.
• A shared future catalog for German STT, anonymous diarization, and fixed-voice TTS variants, with model payloads also excluded from the base ISO.
• Anonymous speaker diarization that assigns transcript segments to file-local labels such as SPEAKER_00, without identifying people.
• Matching preinstalled Codegeist Linux native releases for each supported system architecture.
• Architecture-specific QEMU VMs and bootable GNOME live ISOs built from shared policy modules.
• codegeist --version in the model-free image and one offline ask smoke under the restricted AI identity using an externally injected, catalog-approved test bundle that is absent from the release image.

The first ISOs are intended to become reproducible model-free live images, not yet disk installers. Live-ISO hardware ranking, model selection, online download, offline package import, persistent model storage, live microphone capture, speaker identification, voice cloning, desktop control, general file access, privileged actions, and a general human approval interface remain later milestones. The future installer may rank compatible variants, but the human selects one or supplies a catalog-approved package.

Current State

• The architecture and cross-repository artifact contracts are documented.
• NixOS is selected as the Version 1 base, but no NixOS configuration, VM, ISO, package, service, AI account, or test has been implemented in this repository.
• GNOME, x86_64 UEFI, aarch64 UEFI, and model-free architecture-specific images are target decisions, not current build outputs.
• Ollama is the selected first inference runtime, but it is not configured here yet.
• The variant catalog, external test-bundle path, accelerator profiles, accelerated speech, and anonymous diarization are design requirements, but no selector, installer, model store, CUDA-capable development container, speech package, or hardware smoke is implemented yet.
• Human approval, audit, rollback, and recovery remain design requirements, not implemented security controls.
• This repository is public through its GitHub mirror. Do not commit private planning material, credentials, personal data, model weights, or restricted artifacts.

Documentation

• docs/architecture.md defines the selected Version 1 system architecture and identity boundaries.
• docs/base-system-selection.md records the NixOS decision and the stable Nix, no-Flakes policy.
• docs/artifact-contract.md defines model-free image inputs, the shared LLM and speech catalog, hardware profiles, external test bundles, fixtures, and per-system Codegeist releases.
• docs/build-workflow.md defines the independent catalog, CLI, model-free VM and live ISO, external-bundle, and hardware-profile verification flow.
• docs/speech-model-evaluation.md records the local TTS/STT hardware smoke, candidate models, diarization research, licenses, and first accelerator-profile direction.
• docs/security.md defines least-privilege, isolation, artifact, audit, disablement, and recovery requirements.
• docs/memory-bank/chat.md records compact current project state.

Workspace Kits

.devcontainer/ and .opencode/ are Git submodules that track the release branches of the shared Codegeist development and agent kits. Initialize them from this repository with:

git submodule update --init .devcontainer .opencode

Source References

refs/codegeist/ and refs/codegeist-llm/ are read-only source-reference submodules that track main on the public GitHub repositories. They support cross-repository review and contract work without making either mutable source tree an OS build input. Normal VM and ISO builds must continue to consume only reviewed native releases, manifests, catalogs, and hashes from docs/artifact-contract.md.

Initialize all workspace submodules with:

git submodule update --init \
  .devcontainer .opencode refs/codegeist refs/codegeist-llm

Updating a reference submodule changes a real parent-repository gitlink and must be reviewed explicitly. Both reference repositories track main, but the parent repository always records a concrete commit.

Hosting

Gitea at git.codegeist.ai is the primary write target. GitHub at github.com/codegeist-ai/codegeist-os is a public push mirror of Git refs. Issues, pull requests, secrets, permissions, and other platform state are not automatically synchronized.

TLS Trust

Development environments should trust the certificate authority used by the Gitea deployment and keep Git TLS verification enabled. Installing that CA in the environment trust store is the required long-term fix.

This repository currently carries an explicit temporary exception in .codegeist/Dockerfile: GIT_SSL_NO_VERIFY=true disables certificate verification for every Git HTTPS request made inside the rebuilt devcontainer, including non-Gitea hosts. It does not provide Gitea authentication and does not affect host-side submodule initialization before the container starts. Never put a Gitea token in a remote URL, Dockerfile, environment committed to Git, or other tracked file. Remove the exception as soon as the Gitea CA is trusted.

License Status

No project or distribution license has been selected. Base-system, package, model, firmware, driver, and image-distribution rights must be reviewed before a build or release is produced.