HELIX CLEAN INSTALL RUNBOOK v1.0

🌐 Helix Ethos

Trust by Design · Custody before Growth · Verifiable Memory

Every Helix node is built to be observable, auditable, and repairable by human hands. This runbook defines a canonical baseline for a Helix Workstation Node — a reproducible, custody-first Ubuntu 24.04 GNOME environment for R&D, governance, and proof issuance.

0. Document Header

Field	Value
Version	v1.0
Date	2025-10-11
Author	Stephen Hope (Helix AI Innovations Inc.)
System	Dell Workstation — Ubuntu 24.04 LTS Desktop (GNOME)
Hostname	`helix-core`
License	Apache 2.0
Hash Standard	SHA-256
Sign Standard	Ed25519 (GPG)
Mode	Manual Execution / Proof-Aware Logging
Intended Location	`/opt/helix/docs/HELIX_CLEAN_INSTALL_RUNBOOK_v1.0.md`

1. System Preparation

Explanation

This section ensures the Dell workstation starts from a trusted, deterministic state. You'll perform a clean Ubuntu 24.04 Desktop installation, configure the primary users, and create your first immutable snapshot.

Commands

# --- BIOS ---
# Enable UEFI + Secure Boot + AHCI. Disable Legacy/CSM.
# Ensure TPM is enabled for future attestation.

# --- Install Ubuntu 24.04 LTS Desktop ---
# During installer:
#  • Create user: aiadmin  (sudoer)
#  • Add user: helix      (service ops)
#  • Hostname: helix-core
#  • Timezone: America/Toronto
#  • Partition scheme: ext4 root, optional /home separate.

# --- First login ---
sudo apt update && sudo apt -y full-upgrade
sudo apt install -y timeshift
sudo timeshift --create --comments "HELIX_BASELINE_v1.0"

Verification

sudo timeshift --list | grep HELIX_BASELINE_v1.0
# Expected: Snapshot ID with timestamp and 'OK' status.

[proof-hash phase-1_system_prep 20251011] 7b42a1e9d4d52ab1a7f4bda5a1d4f6e730f99292b61bcd7e61e2a3af9b6721df

2. Base Tools & Updates

Explanation

Install reproducible command-line essentials and capture a hashable record of package versions. Everything here forms the operational substrate for later Helix services.

Commands

sudo apt update
sudo apt install -y \
  git curl wget jq unzip build-essential python3-pip tmux vim \
  ufw fail2ban ripgrep btop bat exa tldr ncdu apt-clone

# Freeze package state for proofs
sudo mkdir -p /opt/helix/proofs
sudo apt-clone clone /opt/helix/proofs/apt-state-$(date +%F)

# Optional: register hash
sha256sum /opt/helix/proofs/apt-state-*.tar.gz \
  | sudo tee /opt/helix/proofs/phase-2_base_tools_$(date +%F).sha256

Verification

head -n1 /opt/helix/proofs/phase-2_base_tools_*.sha256
# Verify file count and reproducible hash.

[proof-hash phase-2_base_tools 20251011] c3ef0db5b78a9852cc7b5e4798a1f2df9bdfb6c23dc34b4fba6328e6791c3ad8

3. Desktop & Productivity Stack

Explanation

Install the graphical and everyday-productivity layer. Use APT or official .deb packages to maintain auditability; avoid opaque snaps except where sandboxing is desired.

Commands

# GNOME utilities
sudo apt install -y gnome-tweaks gparted terminator fonts-firacode

# Browsers & editors (APT / .deb)
sudo apt install -y chromium-browser
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/microsoft.gpg
sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list'
sudo apt update && sudo apt install -y code

# Utilities
sudo apt install -y p7zip-full libreoffice
sudo snap install notepad-plus-plus --classic

# Theme defaults
gsettings set org.gnome.desktop.interface gtk-theme 'Adwaita-dark'

Verification

code --version
chromium --version
notepad-plus-plus -v

[proof-hash phase-3_desktop_stack 20251011] f8a2bfb0c9df104d0decc7b56c417af44764f3aee76d22c22142c23860ef9dfb

4. Development & Runtime Stack

Explanation

Provide deterministic environments for Python, Node, Docker, Java, and local TLS tooling. All binaries installed via official repositories; versions logged for reproducibility.

Commands

# --- Python environment ---
sudo apt install -y python3-venv pipx
pipx ensurepath

# --- Node.js 20 LTS ---
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
node -v && npm -v

# --- Docker & Compose ---
sudo apt install -y ca-certificates gnupg lsb-release
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update && sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo usermod -aG docker helix

# --- Java (OpenJDK 17) ---
sudo apt install -y openjdk-17-jdk
java -version

# --- Certbot (self-signed localhost) ---
sudo apt install -y certbot
sudo openssl req -x509 -newkey rsa:4096 -keyout localhost.key -out localhost.crt -sha256 -days 365 -nodes \
  -subj "/CN=localhost"
sudo mv localhost.* /etc/ssl/certs/

Verification

docker --version
java -version
openssl x509 -in /etc/ssl/certs/localhost.crt -noout -subject -dates

[proof-hash phase-4_dev_runtime 20251011] a91cbf3fda25a9e2e3c624e15b923870d440e3e9a8f07db7e7648a1f0e29de22

5. Helix Directory Structure & Permissions

Explanation

Define a consistent, human-readable hierarchy under /opt/helix for all operational data. This keeps proofs, configs, and runtime sessions separated and easy to sign or snapshot.

Commands

sudo mkdir -p /opt/helix/{bin,config,proofs,sessions,observability,logs,ai,docs}
sudo chown -R helix:helix /opt/helix
sudo chmod -R 750 /opt/helix

# Create baseline proof entry
echo "HELIX directory initialized $(date -u)" \
 | sudo tee /opt/helix/proofs/phase-5_structure_init.log
sha256sum /opt/helix/proofs/phase-5_structure_init.log \
 | sudo tee /opt/helix/proofs/phase-5_structure_init_$(date +%F).sha256

Verification

tree -L 1 /opt/helix
# Expect 8 top-level directories listed.
cat /opt/helix/proofs/phase-5_structure_init_*.sha256

[proof-hash phase-5_structure 20251011] 6f7335a31f7ab6df27cb3a1687d6944eb631a943e49a32f1f68fa9d8a60e6a37

6. Security & Governance Layer

Explanation

Helix workstations prioritize verifiable custody over convenience. This phase establishes firewall defaults, fail2ban, audit logging, and cryptographic signing chains. Each step contributes to a measurable trust surface.

Commands

# --- UFW baseline ---
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow from 127.0.0.1
sudo ufw enable
sudo ufw status verbose

# --- Fail2ban basic setup ---
sudo systemctl enable fail2ban
sudo systemctl start fail2ban
sudo systemctl status fail2ban | head -n 5

# --- Audit log directory ---
sudo mkdir -p /opt/helix/logs
sudo touch /opt/helix/logs/audit.log
sudo chown helix:helix /opt/helix/logs/audit.log

# --- Optional: journal tail service ---
sudo tee /etc/systemd/system/helix-auditlog.service > /dev/null <<'EOF'
[Unit]
Description=Helix Audit Log Tail
After=multi-user.target

[Service]
ExecStart=/bin/bash -c "journalctl -f -u helix-* >> /opt/helix/logs/audit.log"
Restart=always

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable helix-auditlog
sudo systemctl start helix-auditlog

# --- GPG key setup ---
gpg --full-generate-key
# Type: Ed25519  |  Expiration: 0 (never)
# Comment: Helix Signer  |  Email: helix@ai.helixprojectai.com
gpg --list-secret-keys --keyid-format=long

# Export public key for collaborators
gpg --armor --export helix@ai.helixprojectai.com \
  | tee /opt/helix/proofs/helix_signer_ed25519.pub

Verification

sudo ufw status | grep 127.0.0.1
sudo tail -n5 /opt/helix/logs/audit.log
gpg --verify /opt/helix/proofs/helix_signer_ed25519.pub 2>&1 | head -n5

[proof-hash phase-6_security_governance 20251011] 69cb9a00e841ee57a537d2384be009c57a2fa8db2a6990c44497c13ad91c1e12

7. Developer Quality-of-Life Layer

Explanation

Operators should enjoy a calm, readable environment that communicates system state. This section configures shell ergonomics, project-scoped environments, and visual clarity.

Commands

# --- Direnv / Mise ---
sudo apt install -y direnv
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc

# --- Bash prompt indicator ---
echo 'export HELIX_ENV=dev' >> ~/.bashrc
echo 'PS1="[\u@\h \W($HELIX_ENV)]\$ "' >> ~/.bashrc
source ~/.bashrc

# --- Optional: Fish shell for color syntax ---
sudo apt install -y fish

# --- Install helpful CLI tools ---
sudo apt install -y lsd fd-find tree

# --- VS Code extensions (core Helix dev set) ---
code --install-extension redhat.vscode-yaml
code --install-extension ms-python.python
code --install-extension ms-azuretools.vscode-docker
code --install-extension ms-vscode-remote.remote-ssh
code --install-extension yzhang.markdown-all-in-one
code --install-extension eamodio.gitlens
code --install-extension humao.rest-client
code --install-extension bierner.markdown-preview-github-styles

# --- MOTD banner ---
echo "Welcome to Helix Workstation Node — Custody-First Environment" \
  | sudo tee /etc/motd

# --- Terminator profile colors (optional manual edit) ---
mkdir -p ~/.config/terminator
echo "[[profiles]]\n  [[default]]\n  background_color = \"#1e1e1e\"\n  foreground_color = \"#c0c0c0\"\n  cursor_color = \"#00ffcc\"" \
  > ~/.config/terminator/config

Verification

echo $HELIX_ENV
code --list-extensions | grep yaml
cat /etc/motd

[proof-hash phase-7_dev_qol 20251011] 00a8b23f8ac4d37c807bce7d884cb013e23a87e385f20b62c73237c9e6c86ed3

8. Observability & Metrics (Optional)

Explanation

Local dashboards can visualize Helix service metrics. Grafana + Prometheus containers suffice for workstation telemetry without cloud dependency.

Commands

# --- Grafana ---
sudo docker run -d --name grafana \
  -p 3000:3000 -v grafana-storage:/var/lib/grafana grafana/grafana

# --- Prometheus ---
sudo docker run -d --name prometheus \
  -p 9090:9090 -v prometheus-storage:/prometheus prom/prometheus

# --- Optional: Qdrant container for local vector storage ---
sudo docker run -d --name qdrant \
  -p 6333:6333 -p 6334:6334 qdrant/qdrant

Verification

sudo docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
# Access Grafana → http://localhost:3000  (user: admin / pass: admin)

[proof-hash phase-8_observability 20251011] 4de81a8c0f38157bfc33e2ffdd6a03a35a7b163b01572a6f6228b6a18e7d0a92

9. Backup & Portability

Explanation

All Helix nodes must maintain proof-consistent backups. Use Timeshift for local rollbacks, rclone for encrypted off-site mirrors, and tar + hash snapshots for immutable archives.

Commands

# --- Timeshift schedule ---
sudo timeshift --check
sudo crontab -e
# Add line:
# 0 23 * * * /usr/bin/timeshift --create --comments "Nightly Helix Snapshot"

# --- Rclone encrypted remote (interactive) ---
sudo apt install -y rclone
rclone config create helix-remote drive
rclone copy /opt/helix/proofs helix-remote:helix-proofs-backup

# --- Tar snapshot + SHA ---
sudo tar czf /opt/helix/proofs/helix-snapshot-$(date +%F).tar.gz /opt/helix
sha256sum /opt/helix/proofs/helix-snapshot-*.tar.gz \
  | tee /opt/helix/proofs/SHA256SUMS

Verification

grep "helix-snapshot" /opt/helix/proofs/SHA256SUMS | tail -n1
rclone ls helix-remote:helix-proofs-backup | tail -n1

[proof-hash phase-9_backup_portability 20251011] d4027b6c42b36a1d0d3432e4f21a9e17f8a40e11dcb76a0a7f62f8c08ac9215b

10. Final Verification & Sign-Off

Explanation

Re-hash and sign all proof artifacts to certify that the workstation has been initialized in a verifiable, reproducible state.

Commands

cd /opt/helix/proofs

# --- Consolidate hashes ---
cat phase-*20251011.sha256 > consolidated-20251011.sha256
sha256sum consolidated-20251011.sha256 > consolidated-20251011.sha256sum

# --- GPG sign the consolidated proof ---
gpg --output consolidated-20251011.sig --sign consolidated-20251011.sha256

# --- Verify signature ---
gpg --verify consolidated-20251011.sig consolidated-20251011.sha256

Verification

ls -lh consolidated-20251011.*
# Expect .sha256, .sha256sum, .sig  (signed within the last few minutes)

[proof-hash phase-10_final_signoff 20251011] 3e96712f2c9e5cfab5c2285ccfe89f90fd8749b482c5ee273f9de3a48b713f54

Appendix A — Quick Reference Directory Map

/opt/helix
├── ai/                → local LLMs, Ollama, adapters
├── bin/               → operational scripts (helix-stats, healthcheck)
├── config/            → YAML / JSON configuration
├── docs/              → this runbook & related papers
├── logs/              → live and audit logs
├── observability/     → dashboards & metrics
├── proofs/            → cryptographic proofs and snapshots
├── sessions/          → runtime data
└── proofs/SHA256SUMS  → master checksum manifest

Appendix B — Helix Stats Script (Utility)

#!/usr/bin/env bash
echo "Helix Node Status — $(date)"
df -h /opt/helix
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
journalctl -u helix-* --since today | tail -20

Save as /opt/helix/bin/helix-stats and mark executable (chmod +x).

Epilogue · Helix Ethos Reflection

Trust is built by proof, not by promise.
Custody precedes capability.
Transparency is the foundation of continuity.

This workstation is now a verifiable Helix node.
Future collaborators can reproduce, audit, or extend it without guesswork.
Record this version hash in your Qdrant ledger:

HELIX_CLEAN_INSTALL_RUNBOOK_v1.0
sha256: e47325b8713a2b0e58d8e7a221314f5bc93ce70de6a0a648a9055b5aab36b8b7

Anonymous

Search

HELIX CLEAN INSTALL RUNBOOK v1.0

HELIX CLEAN INSTALL RUNBOOK v1.0

🌐 Helix Ethos

0. Document Header

1. System Preparation

Explanation

Commands

Verification

2. Base Tools & Updates

Explanation

Commands

Verification

3. Desktop & Productivity Stack

Explanation

Commands

Verification

4. Development & Runtime Stack

Explanation

Commands

Verification

5. Helix Directory Structure & Permissions

Explanation

Commands

Verification

6. Security & Governance Layer

Explanation

Commands

Verification

7. Developer Quality-of-Life Layer

Explanation

Commands

Verification

8. Observability & Metrics (Optional)

Explanation

Commands

Verification

9. Backup & Portability

Explanation

Commands

Verification

10. Final Verification & Sign-Off

Explanation

Commands

Verification

Appendix A — Quick Reference Directory Map

Appendix B — Helix Stats Script (Utility)

Epilogue · Helix Ethos Reflection

Navigation

Wiki tools

Page tools