PC Agent Installer

🌐 Sprachen: Deutsch | English

Ein öffentliches Template für dokumentierte, reproduzierbare und rollbackfähige Rechner-Einrichtung mit Codex oder anderen lokalen Agenten.

Schnellstart · Arbeitsmodell · Internationalisierung · Validierung · Architektur · Mitwirken · Security

Überblick

PC Agent Installer ist eine Agenten-Arbeitsbasis: Ein Nutzer klont dieses Template, startet Codex im Repository und lässt den Agenten anhand von AGENTS.md, Vorlagen und Guard-Skripten prüfen, dokumentieren und validieren.

Das Zielbild ist ein Agent als Ersatz für einen echten Systemadministrator bei der Ersteinrichtung eines frisch installierten PCs oder Servers. Der Nutzer installiert nur das Betriebssystem und startet danach den Agenten. Der Agent soll dann, nach klarer Vollzugriff-Warnung und Freigabe, die komplette Grundkonfiguration übernehmen: Paketquellen, Updates, Benutzer, Gruppen, Rechte, Firewall, Dienste, Sicherheitsrichtlinien, Entwickler- oder Alltagswerkzeuge, Baseline, Validierung und Rollback-Dokumentation.

Wichtig: Für diese Aufgabe muss Codex mit einem bewusst gewählten Vollzugriff-Profil gestartet werden. Das ist kein optionaler Komfortmodus, sondern die technische Voraussetzung des Produkts. Ohne Administrator-, root-, sudo- oder passende Runtime-Rechte kann der Installer keine vollständige Ersteinrichtung leisten und darf den Lauf nicht als abgeschlossen bewerten.

Das Projekt trennt bewusst zwei Welten:

• öffentliches Template: generische Vorlagen, Skripte, Schemas, Beispiele, Dokumentation und Sicherheitsregeln
• private Operational-Arbeit: echte Hostdaten, Baselines, Rollbacks, lokale Infrastrukturinformationen und Secret-Referenzen

Das Repository ist nicht primär als manuell bedientes Admin-Tool gedacht. Der normale Ablauf ist agentenorientiert: Regeln lesen, Repo-Modus prüfen, Sichtbarkeit bewerten, Public/Private-Einordnung treffen, dann klein und nachvollziehbar arbeiten.

Vor echter Host-Arbeit gibt es eine nutzerfreundliche Erststart-Konfiguration. Der Agent muss sie öffnen oder darauf hinweisen, dass sie noch nicht abgeschlossen ist. Erst danach darf er Baselines erfassen, Sicherheitsoptionen empfehlen oder systemwirksame Schritte vorbereiten.

Der Nutzer muss vor jeder echten Ersteinrichtung verstehen, dass der Agent für diese Aufgabe mit absoluten Systemrechten arbeitet und je nach Betriebssystem als Administrator, root, über sudo oder mit Runtime-Adminrechten handelt. Ohne diese Rechte kann der Agent Firewall, Paketmanager, Dienste, Benutzer, Gruppen, Sicherheitsrichtlinien und Systempakete nicht vollständig einrichten. Vollzugriff ist dabei die vorgesehene Betriebsart, aber keine Freigabe zum Blindflug: Der Agent muss vorher Ist-Zustand, Soll-Zustand, Risiken, Rückbau und Nutzerfreigabe dokumentieren.

Plattform	Erforderlicher Startkontext für echte Ersteinrichtung
Windows	Codex/Agent in erhöhter Administrator-Sitzung, wenn UAC, Windows Features, Dienste, Firewall, Registry oder winget systemweit geändert werden sollen
Linux	Agent als root oder mit bewusst freigegebenem sudo-Kontext, wenn Paketmanager, systemd, Firewall, Benutzer, Gruppen oder Sicherheitsrichtlinien betroffen sind
Debian/Ubuntu	root/sudo plus explizite Freigabe über den OS-Apply-Flow, etwa PC_AGENT_ALLOW_SYSTEM_CHANGES=true
macOS	Administrator-Konto mit gezielten sudo-Aktionen für Paketmanager, Firewall, FileVault-/Gatekeeper-nahe Einstellungen oder LaunchServices
WSL	root/sudo innerhalb der Distribution und getrennte Bewertung, ob Änderungen nur die Distribution oder auch Windows/WSL-Integration betreffen
Container	root oder passende Runtime-Rechte innerhalb der Zielumgebung; Host-Mounts, Ports, Volumes und Daemon-Änderungen bleiben gesondert freigabepflichtig

Was dieses Template leistet

Bereich	Zweck
Repo-Guards	template, operational und local-only sicher unterscheiden
Sichtbarkeitsprüfung	verhindern, dass Hostdaten in ein öffentliches Repository geschrieben werden
Vorlagen	numerische Agenten-Schritte für Windows, Linux, WSL, macOS, Container und Hardwareprofile
Baseline- und Change-Hilfen	Hostzustände in privaten oder lokalen Operational-Repositories dokumentieren
Validierung	Struktur, Frontmatter, Skript-Syntax, Encoding, Secret-Pattern und Git-Diff prüfen
Dokumentation	Agenten-first-Ablauf, Sicherheitsmodell, Rollback-Konzept und Workspace-Hygiene beschreiben
Internationalisierung	Deutsch als Standardsprache, Englisch als Alternativsprache und UTF-8-/Unicode-Prüfung bereitstellen
Produktkomponenten-i18n	Produktnahe Modulnamen und Kurzbeschreibungen in zwölf Sprachen zentral bereitstellen
Vollständige Ersteinrichtung	OS-spezifische Zielzustände für Pakete, Benutzer, Dienste, Firewall und Sicherheitsrichtlinien agentisch umsetzen

Grenzen

• Im Modus template werden keine Hostdaten geschrieben.
• Klartext-Secrets, Tokens, private Schlüssel, produktive Kubeconfigs und rohe Credential-Dumps sind verboten.
• Es gibt keinen Paketmanager, keine externen Laufzeitabhängigkeiten und keinen klassischen Build-Schritt.
• Systemwirksame Änderungen gehören nur in bestätigte private operational-Repositories oder in einen local-only-Klon.

Schnellstart

git clone https://github.com/adrianweidig/pc-agent-installer.git
cd pc-agent-installer

Starte danach Codex oder einen vergleichbaren lokalen Agenten in diesem Verzeichnis. Für reine Analyse reicht ein normales Profil. Für echte Ersteinrichtung muss der Agent mit dem passenden Vollzugriff-Profil des Zielsystems gestartet werden; Details stehen in docs/23-codex-root-profil.md.

Geeignete Startsignale sind zum Beispiel:

Codex, lies dieses Repository und starte die Agenten-Konfiguration für meinen PC.
Codex, in diesem Verzeichnis: starte die Erstkonfiguration.
Codex, öffne die Agenten-Konfiguration erneut und deaktiviere Docker-Empfehlungen.

Der Agent soll daraus selbst den passenden Ablauf ableiten. Er liest zuerst AGENTS.md und Vorlage/common/00-agent-regeln.md, prüft Git-Status, Repo-Modus, Sichtbarkeit und offene Issues, entscheidet zwischen öffentlichem Template und privater Operational-Arbeit und startet erst dann die passende Konfigurationsumgebung.

Im öffentlichen template-Modus darf der Agent keine Hostdaten schreiben. Wenn die Anfrage echte PC-Konfiguration betrifft, muss er zuerst in eine sichere private Operational-Kopie oder einen local-only-Klon wechseln. Die Skripte in scripts/ sind dafür Werkzeuge, keine manuelle Pflichtliste.

Wiederaufnehmbare Konfiguration

Die Agenten-Konfiguration kann jederzeit erneut gestartet werden. Eine bestehende Datei unter hosts/<HOSTNAME>/state/first-run-config.yaml wird als Vorbelegung genutzt; Optionen können dadurch wie Schalter aktiviert oder deaktiviert werden.

Eine deaktivierte Option bedeutet: Der Agent darf diese Fähigkeit künftig nicht mehr vorbereiten oder empfehlen. Wenn dazu bereits systemwirksame Änderungen ausgeführt wurden, entscheidet der Agent nicht blind, sondern prüft Change-Einträge, Rollback-Dateien, Baseline und Soll-Ist-Abgleich und schlägt dann einen sicheren Rückbau oder eine bewusste Beibehaltung vor.

Entdeckbare Werkzeuge

Diese Befehle sind Anker für Agenten und für manuelle Diagnose. Der normale Einstieg bleibt die natürliche Aufforderung oben.

Zweck	PowerShell	Bash
Repo-Modus erkennen	./scripts/common/detect-repo-mode.ps1	bash ./scripts/common/detect-repo-mode.sh
Template prüfen	./scripts/common/verify-template.ps1	bash ./scripts/common/verify-template.sh
Host-Schreibrechte prüfen	./scripts/common/assert-private-repo.ps1	bash ./scripts/common/assert-private-repo.sh
Agenten-Konfiguration starten oder erneut öffnen	./scripts/common/first-run-config.ps1	bash ./scripts/common/first-run-config.sh
Host-Arbeitsbereitschaft prüfen	./scripts/common/assert-first-run-config.ps1 und ./scripts/common/assert-infrastructure-snapshot.ps1	bash ./scripts/common/assert-first-run-config.sh und bash ./scripts/common/assert-infrastructure-snapshot.sh
Produktkomponenten je Sprache anzeigen	./scripts/common/list-product-components.ps1 -Language es	bash ./scripts/common/list-product-components.sh es

assert-private-repo.* darf im öffentlichen template-Modus absichtlich fehlschlagen. Das ist eine Sicherheitsgrenze und schützt vor versehentlichem Schreiben von Hostdaten.

Der Infrastruktur-Snapshot bleibt die Vollzugriff-Sicherheitsgrenze: bevor der Agent installiert, löscht, Dienste ändert, Container anfasst oder Paketmanager nutzt, muss er Ist-Zustand und Soll-Zustand vergleichen und Duplikate sowie Löschrisiken dokumentieren.

Arbeitsmodell

Der normale Nutzerfluss:

1. Nutzer erstellt eine eigene Kopie dieses Templates.
2. Nutzer startet Codex oder einen vergleichbaren Agenten im Repository.
3. Der Agent liest AGENTS.md und Vorlage/common/00-agent-regeln.md.
4. Der Agent prüft Repo-Modus, Git-Status, Sichtbarkeit und offene Issues.
5. Der Agent entscheidet, ob eine Änderung ins öffentliche Template oder in eine private Operational-Struktur gehört.
6. Der Agent führt Änderungen klein, dokumentiert, überprüfbar und rollbackfähig aus.

Offizielle Template-Änderungen bleiben im öffentlichen Repository. Reale Rechnerzustände, lokale Testziele, Infrastrukturdetails und Secret-Referenzen gehören in ein privates operational-Repository oder einen local-only-Klon.

Betriebsmodi

Modus	Zweck	Hostdaten	Remote
template	öffentliches Template	verboten	öffentlich erlaubt
operational	private Betriebsdokumentation	erlaubt, ohne Klartext-Secrets	privat erforderlich
local-only	lokaler Arbeitsklon ohne Remote	erlaubt, ohne Klartext-Secrets	kein Remote

Der aktuelle Modus steht in repo-mode.yaml.

Internationalisierung

Deutsch ist die Standardsprache dieses Projekts. Englisch ist die gepflegte Alternativsprache für internationale Nutzer. GitHub übersetzt die normale Repository-Ansicht nicht automatisch nach Besuchersprache; deshalb nutzt dieses Repository sichtbare Sprachlinks und separate Dateien:

• README.md ist die deutsche Standard-README.
• README.en.md ist die englische README.
• docs/ bleibt die deutsche Standarddokumentation.
• docs/de/index.md ist der deutsche Dokumentationseinstieg.
• docs/en/index.md ist der englische Dokumentationseinstieg.
• Community-Dateien haben deutsche Standardversionen und englische Alternativen, sofern der Inhalt international relevant ist.

Die interaktive Erststart-Konfiguration unterstützt eine gespeicherte Spracheinstellung in hosts/<HOSTNAME>/state/first-run-config.yaml. Die Erkennung folgt dieser Reihenfolge: expliziter Skriptparameter, gespeicherte Projektkonfiguration, PC_AGENT_LANG, danach Deutsch als stabiler Fallback. UTF-8 bleibt durchgehend erhalten; die Template-Validierung prüft deutsche Umlaute und die i18n-Hilfen für PowerShell und Bash.

Produktkomponenten wie Repo-Guards, Erststart-Konfiguration, Infrastruktur-Snapshot, Validierungssuite und Template-Upstream-Sync sind zusätzlich zentral in zwölf Sprachen lokalisiert: de, en, es, fr, it, pt, nl, pl, tr, ru, zh-Hans und ja. Der Katalog liegt unter i18n/product-components.tsv und wird durch validate-product-i18n.* geprüft.

Details stehen in docs/I18N.md. Die englische Fassung steht unter docs/en/I18N.md.

Private Nutzung

Private Operational-Kopie über GitHub CLI erzeugen:

./scripts/common/create-private-copy.ps1 -Template owner/pc-agent-installer -Destination user/pc-agent-installer-private

Lokalen Operational-Modus ohne Remote aktivieren:

./scripts/common/enable-local-only-mode.ps1

Danach kann in einer sicheren Operational-Umgebung eine Host-Baseline erzeugt werden:

./scripts/powershell/collect-baseline.ps1

Private Operational-Repositories können den aktuellen Stand des öffentlichen Templates dauerhaft über einen eigenen template-Remote ziehen:

./scripts/common/sync-template-upstream.ps1

Details und Konfliktregeln stehen in docs/19-template-upstream-sync.md.

Projektstruktur

AGENTS.md              verbindliche Arbeitsregeln für Codex und andere Agenten
Vorlage/               numerisch sortierte Agenten-Vorlagen
scripts/common/        Repo-Modus, Sichtbarkeit, Validierung und Moduswechsel
scripts/powershell/    Windows-Host-, Baseline- und Change-Hilfen
scripts/bash/          Linux-, WSL-, macOS- und Unix-nahe Hilfen
scripts/container/     Container-, Compose-, Swarm-, Kubernetes-, Podman- und NVIDIA-Erkennung
schemas/               YAML-Schemas für Host-, Baseline-, Change-, Rollback- und Repo-Modus-Daten
i18n/                  Produktkomponenten-Katalog und Sprachliste
docs/                  Konzept-, Sicherheits-, Betriebs- und Validierungsdokumentation
examples/              sichere Beispielartefakte ohne echte Hostdaten
private.example/       Beispiele für private Konfigurationen und Secret-Referenzen
hosts/                 bleibt im Template leer und enthält nur .gitkeep
Dockerfile             generisches GHCR-Validierungsimage für das öffentliche Template

Voraussetzungen

• Git
• PowerShell für Windows-Workflows
• Bash für Linux-, WSL-, macOS- und Unix-nahe Workflows
• Optional: Docker, wenn das GHCR-Validierungsimage lokal gebaut werden soll
• Optional: GitHub CLI gh, wenn GitHub-Sichtbarkeit geprüft oder eine private Kopie erzeugt werden soll

Validierung

Vor Änderungen:

git status --short --branch
./scripts/common/detect-repo-mode.ps1

Nach Template-Änderungen:

./scripts/common/verify-template.ps1

Zusätzlich sinnvoll:

bash ./scripts/common/detect-repo-mode.sh
bash ./scripts/common/verify-template.sh

Die relevanten Projektchecks sind in verify-template.* gebündelt: Guard-Skripte, Template-Struktur, YAML-Frontmatter, PowerShell-/Bash-Syntax, Produktkomponenten-i18n, Encoding, Secret-Scan und Git-Diff-Prüfung.

Dokumentation

Sprach-Einstiege: Deutsch | English

Thema	Dokument
Konzept	docs/00-konzept.md
Public vs. Private	docs/01-public-template-vs-private-operational-repo.md
Private Kopie	docs/02-private-repo-erzeugen.md
Sichtbarkeits-Guard	docs/03-repo-visibility-guard.md
Sicherheitsmodell	docs/04-sicherheitsmodell.md
Secrets Policy	docs/05-secrets-policy.md
Klassische Sicherheitseinstellungen	docs/15-klassische-sicherheitseinstellungen.md
Erststart-Konfiguration	docs/16-erststart-konfiguration.md
Programm- und Installationsempfehlungen	docs/17-programm-und-installationsempfehlungen.md
Infrastruktur-Soll-Ist-Abgleich	docs/18-infrastruktur-soll-ist-abgleich.md
Template-Upstream-Sync	docs/19-template-upstream-sync.md
Allgemeine Computer-Konfiguration	docs/20-allgemeine-computer-konfiguration.md
Produktkomponenten-i18n	docs/21-produktkomponenten-i18n.md
Vollständige Ersteinrichtung	docs/22-ersteinrichtung.md
Codex-Root-Profil	docs/23-codex-root-profil.md
Rollback-Konzept	docs/08-rollback-konzept.md
Architektur	docs/ARCHITECTURE.md
CI/CD	docs/CI_CD.md
GitHub Security Alert Analysis	docs/SECURITY_ALERT_ANALYSIS.md
Test- und Validierungsmodell	docs/13-test-und-validierungsmodell.md
Codex-Arbeitsmodell	docs/12-codex-arbeitsmodell.md
Workspace-Konsolidierung	docs/14-codex-workspace-konsolidierung.md
FAQ	docs/99-faq.md
Release-Prozess	docs/RELEASE_PROCESS.md
Codex-New-Project-Standard	docs/CODEX_NEW_PROJECT_STANDARD.md
Maintainer-Checkliste	docs/MAINTAINER_CHECKLIST.md
Support	SUPPORT.md
Code of Conduct	CODE_OF_CONDUCT.md

Mitwirken

Beiträge sind willkommen, solange sie den Public/Private-Schnitt sauber halten. Besonders hilfreich sind:

• robuste Guard-Skripte
• bessere Template-Validierung
• klarere Dokumentation
• sichere Beispiele ohne echte Hostdaten
• reproduzierbare Fehlerberichte

Bitte lies CONTRIBUTING.md, bevor du einen Pull Request öffnest. Sicherheitsrelevante Hinweise gehören nicht in öffentliche Issues; nutze die Hinweise in SECURITY.md.

Für Support-Erwartungen und öffentliche Issue-Grenzen siehe SUPPORT.md. Für den Umgang miteinander gilt CODE_OF_CONDUCT.md.

Security

Dieses Repository darf keine Klartext-Secrets enthalten. Wenn du versehentlich sensible Daten findest oder eine Schwachstelle vermutest, poste keine vertraulichen Details öffentlich. Folge stattdessen SECURITY.md.

Lizenz

Das öffentliche Template steht unter der Apache License 2.0. Private Operational-Repositories, Hostdaten, lokale Infrastrukturinformationen und Nutzerinhalte, die aus dem Template entstehen, sind nicht Teil des öffentlichen Upstream-Projekts.

Status

Der aktuelle Readiness-Stand ist in CODEX_PROJECT_READINESS.md dokumentiert. Für geplante Veröffentlichungen siehe CHANGELOG.md und docs/RELEASE_PROCESS.md.

Für neue Projekte ist der wiederverwendbare Standard in docs/CODEX_NEW_PROJECT_STANDARD.md dokumentiert. Das unterstützende Bootstrap-Skript liegt unter scripts/apply-codex-project-standard.sh.

Wenn dieses Template dir hilft, öffne gern ein Issue mit Feedback oder schlage eine kleine, überprüfbare Verbesserung per Pull Request vor.