docs: refresh readme and legal info
This commit is contained in:
@@ -1,6 +1,6 @@
|
|||||||
MIT License
|
MIT License
|
||||||
|
|
||||||
Copyright (c) 2025 Serve Zone
|
Copyright (c) 2025 Task Venture Capital GmbH
|
||||||
|
|
||||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
of this software and associated documentation files (the "Software"), to deal
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
|||||||
@@ -1,241 +1,183 @@
|
|||||||
# MOXYTOOL
|
# @serve.zone/moxytool
|
||||||
|
|
||||||
> Proxmox Administration Tool for vGPU setup, VM management, and cluster configuration
|
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.
|
||||||
|
|
||||||
[](https://www.npmjs.com/package/@serve.zone/moxytool)
|
## Issue Reporting and Security
|
||||||
[](https://opensource.org/licenses/MIT)
|
|
||||||
|
|
||||||
## Overview
|
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.
|
||||||
|
|
||||||
MOXYTOOL is a comprehensive command-line tool for managing Proxmox servers, with a focus on simplified vGPU setup and advanced server configuration. Built with Deno and compiled to native binaries for maximum performance and portability.
|
## What It Does
|
||||||
|
|
||||||
## Features
|
- 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.
|
||||||
|
|
||||||
- **vGPU Setup**: Automated installation and configuration of NVIDIA vGPU support on Proxmox
|
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.
|
||||||
- **Cross-Platform**: Native binaries for Linux, macOS, and Windows
|
|
||||||
- **Multi-Architecture**: Support for x64 and ARM64 processors
|
|
||||||
- **Interactive CLI**: User-friendly command-line interface with detailed guidance
|
|
||||||
- **Proxmox Integration**: Deep integration with Proxmox VE for seamless management
|
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
### One-Line Installation (Recommended)
|
Install the released binary:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Download and install MOXYTOOL automatically
|
|
||||||
curl -sSL https://code.foss.global/serve.zone/moxytool/raw/branch/main/install.sh | sudo bash
|
curl -sSL https://code.foss.global/serve.zone/moxytool/raw/branch/main/install.sh | sudo bash
|
||||||
```
|
```
|
||||||
|
|
||||||
This will:
|
Install through the npm package wrapper with pnpm:
|
||||||
- Detect your platform automatically (Linux x64/ARM64, macOS Intel/Apple Silicon, Windows)
|
|
||||||
- Download the latest binary from Gitea releases (~400-500KB)
|
|
||||||
- Install to `/usr/local/bin/moxytool`
|
|
||||||
- Make it available system-wide
|
|
||||||
|
|
||||||
### Via npm (Alternative)
|
|
||||||
|
|
||||||
Install globally using npm:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm install -g @serve.zone/moxytool
|
pnpm add --global @serve.zone/moxytool
|
||||||
```
|
```
|
||||||
|
|
||||||
or with pnpm:
|
The wrapper downloads the matching binary for Linux x64/ARM64, macOS x64/ARM64, or Windows x64 where release assets are available.
|
||||||
|
|
||||||
```bash
|
|
||||||
pnpm install -g @serve.zone/moxytool
|
|
||||||
```
|
|
||||||
|
|
||||||
**Benefits:**
|
|
||||||
- Automatic platform detection and binary download
|
|
||||||
- Easy updates via `npm update -g @serve.zone/moxytool`
|
|
||||||
- Version management with npm
|
|
||||||
- Works with Node.js >=14
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
### Updating MOXYTOOL
|
|
||||||
|
|
||||||
Update to the latest version from the repository:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
moxytool update
|
|
||||||
```
|
|
||||||
|
|
||||||
This command will:
|
|
||||||
- Check the current version
|
|
||||||
- Fetch the latest release from Gitea
|
|
||||||
- Automatically download and install the update if available
|
|
||||||
- Preserve your existing configuration
|
|
||||||
|
|
||||||
### vGPU Setup
|
|
||||||
|
|
||||||
Install and configure NVIDIA vGPU support on your Proxmox host:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo moxytool vgpu-setup
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Arguments
|
|
||||||
|
|
||||||
- `--step <number>` - Force execution at a specific installation step
|
|
||||||
- `--url <url>` - Use a custom driver URL (.run or .zip format)
|
|
||||||
- `--file <path>` - Use a local driver file
|
|
||||||
- `--debug` - Enable debug output mode
|
|
||||||
|
|
||||||
#### Examples
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Basic setup with interactive prompts
|
|
||||||
sudo moxytool vgpu-setup
|
|
||||||
|
|
||||||
# Use a custom driver URL
|
|
||||||
sudo moxytool vgpu-setup --url https://example.com/driver.run
|
|
||||||
|
|
||||||
# Use a local driver file
|
|
||||||
sudo moxytool vgpu-setup --file /path/to/driver.run
|
|
||||||
|
|
||||||
# Resume at a specific step
|
|
||||||
sudo moxytool vgpu-setup --step 2
|
|
||||||
|
|
||||||
# Debug mode
|
|
||||||
sudo moxytool vgpu-setup --debug
|
|
||||||
```
|
|
||||||
|
|
||||||
### Installation Process
|
|
||||||
|
|
||||||
1. **Prerequisites**: Ensure virtualization is enabled in BIOS (Intel Vt-d or AMD IOMMU)
|
|
||||||
2. **Run Setup**: Execute `sudo moxytool vgpu-setup`
|
|
||||||
3. **Follow Prompts**: The installer will guide you through the process
|
|
||||||
4. **Reboot**: System will require a reboot after initial setup
|
|
||||||
5. **Complete Setup**: Run the command again after reboot to finish installation
|
|
||||||
6. **Verify**: Check installation with `mdevctl types`
|
|
||||||
|
|
||||||
### Post-Installation
|
|
||||||
|
|
||||||
After successful installation:
|
|
||||||
|
|
||||||
1. **Verify vGPU profiles**: `mdevctl types`
|
|
||||||
2. **Configure VMs**: Add vGPU devices in Proxmox web UI (VM → Hardware → Add → PCI Device)
|
|
||||||
3. **Install guest drivers**: Download and install NVIDIA vGPU guest drivers in your VMs
|
|
||||||
|
|
||||||
### Community Scripts
|
|
||||||
|
|
||||||
Access and deploy 400+ community-maintained Proxmox installation scripts:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# List all available scripts
|
|
||||||
moxytool scripts list
|
|
||||||
|
|
||||||
# Search for specific applications
|
|
||||||
moxytool scripts search docker
|
|
||||||
moxytool scripts search homeassistant
|
|
||||||
|
|
||||||
# View detailed information
|
|
||||||
moxytool scripts info docker
|
|
||||||
|
|
||||||
# Install a script
|
|
||||||
sudo moxytool scripts run docker
|
|
||||||
|
|
||||||
# Refresh the script index
|
|
||||||
moxytool scripts refresh
|
|
||||||
```
|
|
||||||
|
|
||||||
**Features:**
|
|
||||||
- Automatic daily index updates (cached locally)
|
|
||||||
- 400+ LXC containers and VM templates
|
|
||||||
- Full interactive installation support
|
|
||||||
- Applications include: Docker, Jellyfin, Home Assistant, Pi-hole, Nextcloud, and many more
|
|
||||||
|
|
||||||
**Script Categories:**
|
|
||||||
- Containerization (Docker, Podman, Kubernetes)
|
|
||||||
- Media servers (Plex, Jellyfin, Emby)
|
|
||||||
- Home automation (Home Assistant, Node-RED)
|
|
||||||
- Development tools (GitLab, Jenkins, Gitea)
|
|
||||||
- Network tools (Pi-hole, AdGuard, WireGuard)
|
|
||||||
- Databases (PostgreSQL, MariaDB, MongoDB)
|
|
||||||
- And much more...
|
|
||||||
|
|
||||||
## Requirements
|
## Requirements
|
||||||
|
|
||||||
- Proxmox VE 7.4-9.x
|
- Proxmox VE host for `vgpu-setup` and `scripts run`.
|
||||||
- Root/sudo access
|
- Root privileges for host modification commands.
|
||||||
- Internet connection for downloading scripts/drivers
|
- Internet access to download vGPU installer sources, release binaries, and community scripts.
|
||||||
|
- Deno only when running from source.
|
||||||
|
|
||||||
**Note:** The tool comes as a pre-compiled binary - no runtime dependencies needed!
|
The compiled CLI can be present on non-Proxmox systems for browsing help or cached metadata, but host-changing commands intentionally check for Proxmox.
|
||||||
|
|
||||||
## Supported Platforms
|
## Quick Start
|
||||||
|
|
||||||
- **Linux**: x64, ARM64
|
Show available commands:
|
||||||
- **macOS**: x64, ARM64 (Apple Silicon)
|
|
||||||
- **Windows**: x64
|
```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
|
## Development
|
||||||
|
|
||||||
**Note:** Development requires Deno. End users don't need Deno - they use pre-compiled binaries.
|
|
||||||
|
|
||||||
### Prerequisites
|
|
||||||
|
|
||||||
- Deno 2.x or later
|
|
||||||
- Bash (for compilation scripts)
|
|
||||||
|
|
||||||
### Building from Source
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Clone the repository
|
|
||||||
git clone https://code.foss.global/serve.zone/moxytool.git
|
|
||||||
cd moxytool
|
|
||||||
|
|
||||||
# Run locally with Deno
|
|
||||||
deno task dev
|
deno task dev
|
||||||
|
deno task check
|
||||||
# Compile binaries for all platforms
|
deno task lint
|
||||||
deno task compile:all
|
deno task fmt
|
||||||
|
|
||||||
# Run tests
|
|
||||||
deno task test
|
deno task test
|
||||||
|
deno task compile
|
||||||
```
|
```
|
||||||
|
|
||||||
### Project Structure
|
`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:
|
||||||
moxytool/
|
|
||||||
├── mod.ts # Main entry point
|
|
||||||
├── deno.json # Deno configuration
|
|
||||||
├── package.json # NPM package manifest
|
|
||||||
├── ts/ # TypeScript source files
|
|
||||||
│ ├── moxytool.cli.ts # CLI command definitions
|
|
||||||
│ ├── moxytool.plugins.ts # Plugin imports
|
|
||||||
│ ├── moxytool.logging.ts # Logging setup
|
|
||||||
│ ├── moxytool.paths.ts # Path definitions
|
|
||||||
│ └── index.ts # Node.js entry point
|
|
||||||
├── bin/ # Binary wrapper
|
|
||||||
│ └── moxytool-wrapper.js # NPM binary wrapper
|
|
||||||
├── scripts/ # Build scripts
|
|
||||||
│ ├── compile-all.sh # Compilation script
|
|
||||||
│ └── install-binary.js # Binary installation
|
|
||||||
└── dist/ # Compiled binaries
|
|
||||||
└── binaries/
|
|
||||||
```
|
|
||||||
|
|
||||||
## Credits
|
| 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. |
|
||||||
|
|
||||||
MOXYTOOL uses the excellent [proxmox-vgpu-installer](https://github.com/anomixer/proxmox-vgpu-installer) by anomixer for the core vGPU installation process, which supports Proxmox v9.
|
## Upstream Acknowledgements
|
||||||
|
|
||||||
## License
|
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.
|
||||||
|
|
||||||
MIT License - see [LICENSE](license) file for details
|
## License and Legal Information
|
||||||
|
|
||||||
## Support
|
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.
|
||||||
|
|
||||||
- **Issues**: [https://code.foss.global/serve.zone/moxytool/issues](https://code.foss.global/serve.zone/moxytool/issues)
|
**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.
|
||||||
- **Repository**: [https://code.foss.global/serve.zone/moxytool](https://code.foss.global/serve.zone/moxytool)
|
|
||||||
|
|
||||||
## Related Projects
|
### Trademarks
|
||||||
|
|
||||||
- [NUPST](https://code.foss.global/serve.zone/nupst) - Network UPS Shutdown Tool
|
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.
|
||||||
- [SPARK](https://code.foss.global/serve.zone/spark) - Server Configuration and Management Tool
|
|
||||||
|
|
||||||
---
|
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.
|
||||||
|
|
||||||
Made with ❤️ by [Serve Zone](https://serve.zone)
|
### 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.
|
||||||
|
|||||||
Reference in New Issue
Block a user