MOXYTOOL is a Proxmox helper CLI, written in TypeScript for Node.js, focused on the high-risk jobs that benefit from repeatable automation: NVIDIA vGPU setup and curated Proxmox community script discovery/execution.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

What It Does

Verifies that vGPU setup is being run on a Proxmox host.
Downloads and runs the maintained proxmox-vgpu-installer workflow with optional step, URL, file, and debug arguments.
Indexes Proxmox community script metadata and caches it locally.
Lists, searches, and describes community scripts for LXC containers, VMs, host scripts, and add-ons.
Executes selected community scripts interactively on Proxmox hosts.
Updates itself by checking the latest release on code.foss.global and re-running the installer.
Ships as a single executable (a Node.js single executable application, no Node.js installation needed) and through a small npm package wrapper that downloads it.

MOXYTOOL does not currently implement a full Proxmox API client or general VM lifecycle manager. Its active surface is vGPU setup plus community script operations.

Installation

Install the released binary:

curl -sSL https://code.foss.global/serve.zone/moxytool/releases/download/latest/install.sh | sudo bash

Running MOXYTOOL 2.0.0 or earlier? Those versions fetch the installer from raw/branch/main, which code.foss.global no longer serves without sign-in, so their moxytool update fails. Run the one-liner above once; every later sudo moxytool update works normally.

Install a specific release, or check what the installer would do without changing anything:

curl -sSL https://code.foss.global/serve.zone/moxytool/releases/download/latest/install.sh | sudo bash -s -- --version v2.0.1
curl -sSL https://code.foss.global/serve.zone/moxytool/releases/download/latest/install.sh | bash -s -- --dry-run

install.sh is a release asset like the executables, so these commands need no code.foss.global account; latest is Gitea's alias for the newest release.

The installer puts the executable into /opt/moxytool and links it as /usr/local/bin/moxytool. It installs MOXYTOOL 2.0.0 and later; earlier releases carry no notice files or uninstaller asset. It downloads the executable for the host and the release's SHA256SUMS.txt, refuses a missing or different checksum, and runs the new executable with --version before it touches an existing installation. If a later step fails, it puts the previous installation back. It installs the executable's notice files and uninstall.sh beside it. --version vX.Y.Z installs a given release, --install-dir DIR another directory, and --dry-run checks the release's assets without root and without changing anything. moxytool update asks the public releases API for the newest release and runs that release's install.sh pinned to it.

Install through the npm package wrapper with pnpm:

pnpm add --global @serve.zone/moxytool

The package's install script downloads the executable of the package's version for Linux x64/ARM64, macOS x64/ARM64 or Windows x64 with its notice files and installs them only when they match the release's SHA256SUMS.txt; the moxytool command runs it.

Each release asset comes with <asset>.third-party-notices.txt and .json, the licenses of the Node.js runtime and the bundled npm packages. The Windows x64 executable is built and checked structurally but not smoke-tested on Windows.

Requirements

Proxmox VE host for vgpu-setup and scripts run.
Root privileges for host modification commands.
Internet access to download vGPU installer sources, release binaries, and community scripts.
Linux executables: glibc 2.28 or later, libstdc++.so.6 and libatomic.so.1 (on Debian and Proxmox VE the packages libstdc++6 and libatomic1; install a missing one with apt install libatomic1). Alpine/musl is not supported. Without them the executable does not start, and the installer stops before it changes an existing installation.
Node.js 22 or later and pnpm only when building from source; Deno is not supported.

The compiled CLI can be present on non-Proxmox systems for browsing help or cached metadata, but host-changing commands intentionally check for Proxmox.

Quick Start

Show available commands:

moxytool

Run the vGPU setup wrapper:

sudo moxytool vgpu-setup

Browse community scripts:

moxytool scripts refresh
moxytool scripts search docker
moxytool scripts info docker

Run a script on a Proxmox host:

sudo moxytool scripts run docker

CLI Reference

moxytool <command> [options]

Command	Purpose
`vgpu-setup`	Download and run the Proxmox vGPU installer workflow.
`scripts`	Show community script subcommands.
`scripts list`	List cached script metadata grouped by type.
`scripts search <query> [--filter type:<type>]`	Search by slug, name, or description.
`scripts info <slug>`	Show script metadata, resources, notes, ports, docs, and credentials.
`scripts run <slug>`	Execute a community script interactively. Requires Proxmox.
`scripts refresh`	Rebuild the local script metadata cache.
`update`	Upgrade MOXYTOOL to the latest release.

vgpu-setup forwards these options to the upstream installer:

Option	Purpose
`--step <number>`	Resume or force a specific installer step.
`--url <url>`	Use a custom driver URL.
`--file <path>`	Use a local driver file.
`--debug`	Enable installer debug output.

Community Script Index

ScriptIndex reads the script catalog of the Proxmox VE Helper-Scripts project, the PocketBase server https://db.community-scripts.org that the project's website reads, without an account. It caches the catalog for 24 hours and searches and filters the cached copy. It skips scripts that are still in development (they live in the project's DevScripts repository), deleted or disabled, and scripts for other platforms than Proxmox VE. Each script runs from the ProxmoxVE repository, https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/<path>: the path the catalog names, or else the path that follows from the script's type and slug (ct/<slug>.sh, vm/<slug>.sh, tools/pve/<slug>.sh, tools/addon/<slug>.sh, turnkey/<slug>.sh).

Cache locations:

Path	Purpose
`/etc/moxytool/scripts/index.json`	Cached script metadata.
`/etc/moxytool/scripts/last-index-time`	Reserved last-index tracker path.

The script runner runs the selected script the way the project documents it, bash -c "$(curl -fsSL <script-url>)", on the terminal moxytool runs on, so the script's prompts and menus work. It passes the URL as an argument, never as shell text, and runs only scripts in the repository's ct/, vm/, turnkey/, tools/pve/ and tools/addon/ directories. scripts refresh skips catalog records that name other paths or lack a valid slug, name or type, and keeps the previous index when no script remains or more than a tenth of the records is invalid. Review script metadata and upstream sources before running host-changing scripts.

vGPU Workflow

The vgpu-setup command clones https://github.com/anomixer/proxmox-vgpu-installer into /tmp/moxytool-vgpu-setup, then runs proxmox-installer.sh with the forwarded flags.

Typical flow:

sudo moxytool vgpu-setup
sudo reboot
sudo moxytool vgpu-setup
mdevctl types

After successful setup, configure vGPU devices from the Proxmox web UI and install the matching guest drivers in the VM.

Safety Notes

vgpu-setup modifies the Proxmox host and may require reboots.
scripts run executes third-party community scripts as root.
Keep host backups and out-of-band access ready before changing GPU, kernel, or virtualization configuration.
Use scripts info <slug> before scripts run <slug> to inspect warnings, resource requirements, default credentials, and documentation links.

Development

pnpm install
pnpm build                          # tsbuild: ts/ -> dist_ts/
pnpm exec tsbuild check 'test/**/*' # type check the tests
pnpm test                           # tstest: test/*.node.ts
pnpm run build:binary               # tsbundle + tssea: all five executables
node dist_ts/index.js --version     # run the compiled source

pnpm run build:binary runs tsbundle, which bundles ts/index.ts into dist_node/moxytool.mjs, and then tssea build, which builds the Node.js single executable applications for Linux x64, Linux ARM64, macOS x64, macOS ARM64 and Windows x64 into dist/binaries/ and smoke-runs the one for the build host. Both read their configuration from .smartconfig.json.

Source map:

Path	Purpose
`ts/index.ts`	Executable entry point and source exports.
`ts/moxytool.cli.ts`	Command routing.
`ts/moxytool.classes.scriptindex.ts`	Remote metadata indexing and local cache.
`ts/moxytool.classes.scriptrunner.ts`	Interactive community script execution.
`ts/moxytool.paths.ts`	Data/cache paths.
`install.sh`	Host installer and updater.
`bin/moxytool-wrapper.js`, `scripts/install-binary.js`	npm wrapper and postinstall downloader.
`.gitea/workflows/release.yml`, `scripts/gitzone-binary-release.mjs`	Tag workflow: builds the executables and publishes them, their notices, `install.sh`, `uninstall.sh` and `SHA256SUMS.txt` as a Gitea release.

install.sh, the npm wrapper and postinstall script, the release workflow and its helper are generated by @git.zone/cli from the binaryCli assets configuration in .smartconfig.json. Change the configuration and regenerate them with gitzone format --only assets --write --yes (@git.zone/cli 9.1.0 or later) instead of editing them.

Upstream Acknowledgements

MOXYTOOL wraps the excellent proxmox-vgpu-installer project by anomixer for the vGPU workflow and uses Proxmox community script metadata for the script browser/runner feature. Those upstream projects keep their own licenses, support channels, and operational risks.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@serve.zone/moxytool