osx proxmox next - Moses Yebei

The Problem

Provisioning a macOS VM on Proxmox 9 requires manual OpenCore plist edits, GenSMBIOS runs, and a series of qm commands. Even a seasoned admin can spend 3–6 hours correcting a single flag, and the process must be repeated for every new VM or hardware change.

What This Does

osx-proxmox-next replaces the manual workflow with a six‑step TUI wizard that runs on the Proxmox host. The wizard auto‑detects CPU type, RAM, and storage, downloads the appropriate OpenCore and recovery images, generates a unique SMBIOS, and builds a dry‑run plan that can be inspected before execution.

Key implementation pieces:

CLI entry point – src/osx_proxmox_next/cli.py (_dispatch_simple_commands, _validate_and_fetch_assets).
Application core – src/osx_proxmox_next/app.py (run, _go_next, _preflight_worker).
Domain model – src/osx_proxmox_next/domain.py defines VmConfig, PlanStep, and validation helpers used by 19 other modules.
Planner & executor – src/osx_proxmox_next/planner.py builds the step list; src/osx_proxmox_next/executor.py applies it via the Proxmox CLI wrappers in src/osx_proxmox_next/infrastructure.py.

The repository also ships a static documentation site (docs/ built with React/TypeScript) and a handful of helper shell scripts in scripts/ for profile toggling and demo recording.

How It Is Wired

Execution begins in src/osx_proxmox_next/app.py:run (line 401). run creates a NextApp instance and hands control to the Textual UI loop. The UI drives _go_next, which sequentially invokes the planner (build_plan → PlanStep objects) and then the executor (apply_plan).

Core call hub – src/osx_proxmox_next/domain.py is imported by 19 modules; changes here have the widest blast radius.
Circular dependencies – src/osx_proxmox_next/services/__init__.py, defaults.py, and rollback.py form a 14‑node import cycle, increasing maintenance risk.
Filesystem impact – 68 functions read/write files, e.g., downloader.download_recovery writes the recovered DMG, infrastructure.run_command invokes subprocess.run to execute qm, pvesm, and pvesh.
Network impact – downloader._fetch_github_releases performs outbound HTTP calls to fetch OpenCore assets.
External commands – infrastructure.run_command runs the Proxmox CLI; executor.apply_plan ultimately calls these wrappers for each qm operation.

The internal call graph shows _run (called from 137 places) as the most fan‑out function, followed by _cfg (75) and run_cli (70). These functions are the primary mutation points; any refactor should start there to limit ripple effects.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/osx-proxmox-next
cd osx-proxmox-next

# Install Python dependencies (pyproject.toml)
pip install .   # or: pip install -e .  for editable dev install

# Optional: build the docs site (requires npm)
cd docs
npm ci          # respects the committed package-lock.json
npm run build   # generates static site under docs/build

# Run the wizard (requires root on the Proxmox host)
python -m osx_proxmox_next.app   # launches the TUI
# Or invoke the CLI directly
python -m osx_proxmox_next.cli --help

Configuration is supplied via CLI flags (e.g., --iso-dir for shared storage) and environment variables are not required. The wizard persists no secret material; the only external I/O is the downloaded OpenCore assets and the generated VM definition files.

Real‑World Use

A CI pipeline that provisions a temporary macOS VM for automated UI tests could call:

python -m osx_proxmox_next.cli create \
    --os sonoma \
    --cpu auto \
    --ram 8G \
    --storage local-lvm \
    --dry-run json > plan.json
python -m osx_proxmox_next.cli apply --plan plan.json

The dry‑run JSON can be version‑controlled, enabling reproducible VM builds across test environments.

Code Health & Issues

HIGH – No LICENSE – repository root lacks a license file; redistribution rights are undefined.
HIGH – Missing Python lockfile – pyproject.toml has no accompanying lockfile; transitive dependencies are not pinned.
HIGH – CI steps discard exit codes (.github/workflows/release.yml line 30). Failures are hidden, risking stale artifacts.
HIGH – Direct push to main in CI – release workflow pushes straight to the default branch, bypassing PR review.
MEDIUM – GitHub token permissions – .github/workflows/test.yml declares no permissions: block, granting broader access than needed.
MEDIUM – No Dependabot/Renovate – repository lacks automated dependency updates.
MEDIUM – npm install instead of npm ci – CI reinstalls without lockfile enforcement, allowing version drift.
MEDIUM – No dependency‑vulnerability scan – CI does not run a vulnerability review action.
MEDIUM – Checkout persists credentials – .github/workflows/docs.yml does not set persist-credentials: false.
LOW – No job timeouts – CI jobs lack timeout-minutes, risking runaway runs.

Additional static findings: 14 import cycles, 2 unguarded file opens, duplicated shell script blocks, deep nesting (max depth 7), and several oversized files (>1 800 lines). These increase cognitive load and maintenance cost.

The Bottom Line

osx-proxmox-next delivers a functional, well‑documented wizard that reduces macOS VM provisioning from hours to minutes and integrates cleanly with Proxmox CLI tooling. The codebase is functional but suffers from architectural smells (import cycles, large hub modules) and several high‑severity process issues (missing license, unlocked dependencies, CI practices). It is suitable for teams that need rapid VM setup and are prepared to address the identified health concerns before using it in production‑critical pipelines.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

139 files

Python65
Markdown18
Shell9
YAML7
JSON4
TypeScript2

ReactFlask

Module dependencies

The 10 most depended-upon modules of 69, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_osx_proxmox_next_domain["domain"] n1_oxmox_next_services___init__["__init__"] n2_rc_osx_proxmox_next_defaults["defaults"] n3__proxmox_next_infrastructure["infrastructure"] n4_rc_osx_proxmox_next_rollback["rollback"] n5_rc_osx_proxmox_next_executor["executor"] n6_src_osx_proxmox_next_planner["planner"] n7_c_osx_proxmox_next_preflight["preflight"] n8_src_osx_proxmox_next_assets["assets"] n9_src_osx_proxmox_next_smbios["smbios"] n8_src_osx_proxmox_next_assets --> n2_rc_osx_proxmox_next_defaults n8_src_osx_proxmox_next_assets --> n0_src_osx_proxmox_next_domain n2_rc_osx_proxmox_next_defaults --> n3__proxmox_next_infrastructure n2_rc_osx_proxmox_next_defaults --> n1_oxmox_next_services___init__ n5_rc_osx_proxmox_next_executor --> n3__proxmox_next_infrastructure n5_rc_osx_proxmox_next_executor --> n0_src_osx_proxmox_next_domain n5_rc_osx_proxmox_next_executor --> n1_oxmox_next_services___init__ n6_src_osx_proxmox_next_planner --> n8_src_osx_proxmox_next_assets n6_src_osx_proxmox_next_planner --> n2_rc_osx_proxmox_next_defaults n6_src_osx_proxmox_next_planner --> n0_src_osx_proxmox_next_domain n6_src_osx_proxmox_next_planner --> n3__proxmox_next_infrastructure n6_src_osx_proxmox_next_planner --> n9_src_osx_proxmox_next_smbios n6_src_osx_proxmox_next_planner --> n1_oxmox_next_services___init__ n7_c_osx_proxmox_next_preflight --> n2_rc_osx_proxmox_next_defaults n7_c_osx_proxmox_next_preflight --> n3__proxmox_next_infrastructure n7_c_osx_proxmox_next_preflight --> n1_oxmox_next_services___init__ n4_rc_osx_proxmox_next_rollback --> n3__proxmox_next_infrastructure n4_rc_osx_proxmox_next_rollback --> n1_oxmox_next_services___init__ classDef cyc stroke:#ef4444,stroke-width:2px; class n1_oxmox_next_services___init__,n2_rc_osx_proxmox_next_defaults,n4_rc_osx_proxmox_next_rollback,n5_rc_osx_proxmox_next_executor,n6_src_osx_proxmox_next_planner,n7_c_osx_proxmox_next_preflight,n8_src_osx_proxmox_next_assets cyc;

Findings

MediumNo LICENSE file - unclear usage/redistribution rights root

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high4

medium5

low1

Add a LICENSE; redistribution rights are undefinedhigh

no licence file at the repository root

Fix: Add MIT or Apache-2.0 at the repository root.

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Stop discarding the exit code of steps whose failure mattershigh

.github/workflows/release.yml

lines 30 discard failure

The job reports green while the artifact it was supposed to produce was never produced, so a crash becomes a successful run built on stale data.

Fix: Let the step fail, or test the specific expected condition instead of discarding all exit codes.

Open a pull request instead of pushing to the default branchhigh

.github/workflows/release.yml

git push origin main

Automated commits land on the branch that deploys, with no test having run against the result.

Fix: Push to a bot branch and open a pull request, or restrict the push to a tag ref.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/test.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

2 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Install from the lockfile in CImedium

.github/workflows

npm install with a committed package-lock.json

A fresh resolution in CI means the tested dependency set is not the locked one, so the failure only appears after merge.

Fix: Use npm ci, yarn install --immutable, or pnpm install --frozen-lockfile.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/docs.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/docs.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.