# @serve.zone/moxytool

MOXYTOOL is a Deno-powered Proxmox helper CLI 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/](https://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/](https://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 compiled binary through a small npm package wrapper.

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:

```bash
curl -sSL https://code.foss.global/serve.zone/moxytool/raw/branch/main/install.sh | sudo bash
```

Install through the npm package wrapper with pnpm:

```bash
pnpm add --global @serve.zone/moxytool
```

The wrapper downloads the matching binary for Linux x64/ARM64, macOS x64/ARM64, or Windows x64 where release assets are available.

## 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.
- Deno only when running from source.

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:

```bash
moxytool
```

Run the vGPU setup wrapper:

```bash
sudo moxytool vgpu-setup
```

Browse community scripts:

```bash
moxytool scripts refresh
moxytool scripts search docker
moxytool scripts info docker
```

Run a script on a Proxmox host:

```bash
sudo moxytool scripts run docker
```

## CLI Reference

```bash
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` fetches JSON metadata from the mirrored ProxmoxVE script catalog, caches it for 24 hours, and exposes local search/filter operations.

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 executes the selected script with `bash -c "$(curl -fsSL <script-url>)"`, preserving interactivity for prompts. 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:

```bash
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

```bash
deno task dev
deno task check
deno task lint
deno task fmt
deno task test
deno task compile
```

`deno task compile` delegates to `scripts/compile-all.sh`, which currently builds Linux x64, Linux ARM64, macOS x64, macOS ARM64, and Windows x64 binaries.

Source map:

| Path | Purpose |
| --- | --- |
| `mod.ts` | CLI 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. |
| `scripts/compile-all.sh` | Multi-platform Deno compilation. |
| `scripts/install-binary.js` | npm postinstall binary downloader. |

## 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](./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.

### Company Information

Task Venture Capital GmbH\
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.