VX - Universal Development Tool Manager
One-sentence summary: vx = prefix any dev tool command with vx → it auto-installs the tool and runs it.
vx is a universal development tool manager that automatically installs and manages
development tools (Node.js, Python/uv, Go, Rust, etc.) with zero configuration.
Core Concept
Instead of requiring users to manually install tools, prefix any command with vx:
vx node --version # Auto-installs Node.js if needed
vx uv pip install x # Auto-installs uv if needed
vx go build . # Auto-installs Go if needed
vx cargo build # Auto-installs Rust if needed
vx just test # Auto-installs just if needed
vx is fully transparent - same commands, same arguments, just add vx prefix.
Essential Commands
Tool Execution (most common)
vx <tool> [args...] # Run any tool (auto-installs if missing)
vx node app.js # Run Node.js
vx python script.py # Run Python (via uv)
vx npm install # Run npm
vx npx create-react-app app # Run npx
vx cargo test # Run cargo
vx just build # Run just (task runner)
vx git status # Run git
Tool Management
vx install node@22 # Install specific version
vx install uv go rust # Install multiple tools at once
vx list # List all available tools
vx list --installed # List installed tools only
vx versions node # Show available versions
vx switch node@20 # Switch active version
vx uninstall go@1.21 # Remove a version
Project Management
vx init # Initialize vx.toml for project
vx sync # Install all tools from vx.toml
vx setup # Full project setup (sync + hooks)
vx dev # Enter dev environment with all tools
vx run test # Run project scripts from vx.toml
vx check # Verify tool constraints
vx lock # Generate vx.lock for reproducibility
Environment & Config
vx env list # List environments
vx config show # Show configuration
vx cache info # Show cache usage
vx search <query> # Search available tools
vx info # System info and capabilities
Project Configuration (vx.toml)
Projects use vx.toml in the root directory:
[tools]
node = "22" # Major version
go = "1.22" # Minor version
uv = "latest" # Always latest
rust = "1.80" # Specific version
just = "*" # Any version
[scripts]
dev = "npm run dev"
test = "cargo test"
lint = "npm run lint && cargo clippy"
build = "just build"
[hooks]
pre_commit = ["vx run lint"]
post_setup = ["npm install"]
Using --with for Multi-Runtime
When a command needs additional runtimes available:
vx --with bun node app.js # Node.js + Bun in PATH
vx --with deno npm test # npm + Deno available
Package Aliases
vx supports package aliases — short commands that automatically route to ecosystem packages:
# These are equivalent:
vx vite # Same as: vx npm:vite
vx vite@5.0 # Same as: vx npm:vite@5.0
vx rez # Same as: vx uv:rez
vx pre-commit # Same as: vx uv:pre-commit
vx meson # Same as: vx uv:meson
vx release-please # Same as: vx npm:release-please
Benefits:
- Simpler commands without remembering ecosystem prefixes
- Automatic runtime dependency management (node/python installed as needed)
- Respects project
vx.toml version configuration
Available Aliases:
| Short Command |
Equivalent |
Ecosystem |
vx vite |
vx npm:vite |
npm |
vx release-please |
vx npm:release-please |
npm |
vx rez |
vx uv:rez |
uv |
vx pre-commit |
vx uv:pre-commit |
uv |
vx meson |
vx uv:meson |
uv |
Companion Tool Environment Injection
When vx.toml includes tools like MSVC, vx automatically injects discovery environment variables into all subprocess environments. This allows any tool needing a C/C++ compiler to discover the vx-managed installation.
# vx.toml — MSVC env vars injected for ALL tools
[tools]
node = "22"
cmake = "3.28"
rust = "1.82"
[tools.msvc]
version = "14.42"
os = ["windows"]
Now tools like node-gyp, CMake, Cargo (cc crate) automatically find MSVC:
# node-gyp finds MSVC via VCINSTALLDIR
vx npx node-gyp rebuild
# CMake discovers the compiler
vx cmake -B build -G "Ninja"
# Cargo cc crate finds MSVC for C dependencies
vx cargo build
Injected Environment Variables (MSVC example):
| Variable |
Purpose |
VCINSTALLDIR |
VS install path (node-gyp, CMake) |
VCToolsInstallDir |
Exact toolchain path |
VX_MSVC_ROOT |
vx MSVC root path |
MSVC Build Tools (Windows)
Microsoft Visual C++ compiler for Windows development:
# Install MSVC Build Tools
vx install msvc@latest
vx install msvc 14.40 # Specific version
# Using MSVC tools via namespace
vx msvc cl main.cpp -o main.exe
vx msvc link main.obj
vx msvc nmake
# Direct aliases
vx cl main.cpp # Same as: vx msvc cl
vx nmake # Same as: vx msvc nmake
# Version-specific usage
vx msvc@14.40 cl main.cpp
Available MSVC Tools:
| Tool |
Command |
Description |
| cl |
vx msvc cl |
C/C++ compiler |
| link |
vx msvc link |
Linker |
| lib |
vx msvc lib |
Library manager |
| nmake |
vx msvc nmake |
Make utility |
Supported Tools (114 Providers)
| Category |
Tools |
| JavaScript |
node, npm, npx, bun, deno, pnpm, yarn, vite, nx, turbo |
| JS Tooling |
oxlint, biome |
| Python |
uv, uvx, python, pip, ruff, maturin, pre-commit |
| Rust |
cargo, rustc, rustup |
| Go |
go, gofmt, gws |
| System/CLI |
git, bash, curl, pwsh, jq, yq, fd, bat, ripgrep, fzf, starship, jj, sd, eza, dust, duf, xh, atuin, zoxide, tealdeer, gping, delta, hyperfine, watchexec, bottom |
| TUI/Terminal |
helix, yazi, zellij, lazygit, lazydocker, k9s |
| Build Tools |
just, task, cmake, ninja, make, meson, xmake, protoc, conan, vcpkg, spack |
| DevOps |
kubectl, helm, podman, terraform, hadolint, dagu, actionlint |
| Security |
gitleaks, trivy |
| Cloud CLI |
awscli, azcli, gcloud |
| .NET |
dotnet, msbuild, nuget |
| C/C++ |
msvc, llvm, nasm, ccache, buildcache, sccache, rcedit |
| Media |
ffmpeg, imagemagick |
| Java |
java |
| AI |
ollama, openclaw |
| Other Langs |
zig |
| Container |
dive |
| Config Mgmt |
chezmoi, mise |
| Package Managers |
brew, choco, winget |
| Misc |
gh, prek, actrun, wix, vscode, xcodebuild, systemctl, release-please, rez, 7zip, trippy |
Provider System (Starlark DSL)
All 114 providers are defined using provider.star (Starlark DSL) — a declarative, zero-compilation approach. Each provider lives in crates/vx-providers/<name>/provider.star.
vx uses a two-phase execution model (inspired by Buck2):
- Analysis Phase (Starlark):
provider.star runs as pure computation, returning descriptor dicts. No I/O.
- Execution Phase (Rust): The Rust runtime interprets descriptors for actual downloads, installs, and process execution.
How to add a new tool
# crates/vx-providers/mytool/provider.star
load("@vx//stdlib:provider.star", "runtime_def", "github_permissions")
load("@vx//stdlib:provider_templates.star", "github_rust_provider")
name = "mytool"
description = "My awesome tool"
ecosystem = "custom"
runtimes = [runtime_def("mytool", aliases=["mt"])]
permissions = github_permissions()
# Use a template — covers 90% of tools
_p = github_rust_provider("owner", "mytool",
asset = "mytool-{vversion}-{triple}.{ext}")
fetch_versions = _p["fetch_versions"]
download_url = _p["download_url"]
install_layout = _p["install_layout"]
store_root = _p["store_root"]
get_execute_path = _p["get_execute_path"]
environment = _p["environment"]
Available templates
| Template |
Use case |
Example |
github_rust_provider |
Rust tools on GitHub (most common) |
ripgrep, fd, bat, just, uv |
github_go_provider |
Go tools on GitHub (goreleaser style) |
gh, task |
github_binary_provider |
Single binary download (no archive) |
kubectl |
system_provider |
System package manager only |
7zip |
Template Placeholders
| Placeholder |
Rust template |
Go template |
Description |
{version} |
✓ |
✓ |
Version number (e.g., "1.0.0") |
{vversion} |
✓ |
— |
With v-prefix (e.g., "v1.0.0") |
{triple} |
✓ |
— |
Rust target triple (e.g., "x86_64-unknown-linux-musl") |
{os} |
— |
✓ |
Go GOOS (linux, darwin, windows) |
{arch} |
— |
✓ |
Go GOARCH (amd64, arm64) |
{ext} |
✓ |
✓ |
Archive extension (zip/tar.gz) |
{exe} |
✓ |
✓ |
Executable suffix (.exe/"") |
Starlark Standard Library (14 modules)
Located in crates/vx-starlark/stdlib/. The main entry point is provider.star which re-exports everything:
# Import everything from the unified facade
load("@vx//stdlib:provider.star",
"runtime_def", "bundled_runtime_def", "dep_def",
"github_permissions", "platform_map",
"env_set", "env_prepend",
"archive_layout", "binary_layout")
Key modules:
provider.star — Unified facade (re-exports all)
runtime.star — runtime_def, bundled_runtime_def, dep_def
platform.star — platform_map, platform_select, rust_triple, go_os_arch
env.star — env_set, env_prepend, env_append, env_unset
layout.star — archive_layout, binary_layout, bin_subdir_layout, hooks
provider_templates.star — High-level templates (4 templates)
permissions.star — github_permissions, system_permissions
system_install.star — winget_install, brew_install, apt_install
Important Rules for AI Agents
- Always use
vx prefix when running tools in vx-managed projects
- Use
vx just instead of just for task runner commands
- Use
vx npm instead of npm directly
- Use
vx cargo instead of cargo directly
- Check
vx.toml first to understand project tool requirements
- Use
vx run <script> for project-defined scripts
- Never suggest manual tool installation - vx handles it automatically
- Commands like
vx install are for explicit pre-installation; normal usage auto-installs
- Use correct terminology: Runtime (not Tool), Provider (not Plugin), provider.star (not provider config)
- Provider development: New tools are added via
provider.star Starlark DSL in crates/vx-providers/<name>/
- Tests go in
tests/ dirs — never inline #[cfg(test)] in source files
Version Resolution Priority
vx resolves tool versions in this order (highest to lowest):
- Command-line override:
vx node@22 app.js
- Project vx.toml:
[tools] node = "22"
- Parent directory vx.toml (traverses up to root)
- User global config:
~/.config/vx/config.toml
- Provider default: latest stable version
MCP Integration
vx is MCP-ready — replace npx/uvx with vx in MCP server configurations.
This eliminates the "install Node.js/Python first" requirement for all MCP servers.
Configuration Pattern
{
"mcpServers": {
"example-server": {
"command": "vx",
"args": ["npx", "-y", "@example/mcp-server@latest"]
},
"python-server": {
"command": "vx",
"args": ["uvx", "some-python-mcp-server@latest"]
}
}
}
Real-World MCP Examples
{
"mcpServers": {
"filesystem": {
"command": "vx",
"args": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
},
"github": {
"command": "vx",
"args": ["npx", "-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "<token>" }
},
"sqlite": {
"command": "vx",
"args": ["uvx", "mcp-server-sqlite", "--db-path", "/path/to/db.sqlite"]
}
}
}
Migration Pattern
| Original |
vx-powered |
"command": "npx" |
"command": "vx", "args": ["npx", ...] |
"command": "uvx" |
"command": "vx", "args": ["uvx", ...] |
"command": "node" |
"command": "vx", "args": ["node", ...] |
"command": "python" |
"command": "vx", "args": ["python", ...] |
"command": "bun" |
"command": "vx", "args": ["bun", ...] |
Benefits for AI Agents
- Zero-config: No need to check if Node.js/Python is installed before starting MCP servers
- Version consistency: MCP servers always use the version specified in
vx.toml
- Cross-platform: Same MCP config works on Windows, macOS, and Linux
- CI/CD ready: MCP servers in CI pipelines just work with vx
GitHub Actions Integration
vx provides a GitHub Action (action.yml) for CI/CD workflows. Use it in .github/workflows/ files:
Basic Usage
- uses: loonghao/vx@main
with:
version: 'latest' # vx version (default: latest)
github-token: ${{ secrets.GITHUB_TOKEN }}
Pre-install Tools
- uses: loonghao/vx@main
with:
tools: 'node go uv' # Space-separated tools to pre-install
cache: 'true' # Enable tool caching (default: true)
Project Setup (vx.toml)
- uses: loonghao/vx@main
with:
setup: 'true' # Run `vx setup --ci` for vx.toml projects
Full Example
name: CI
on: [push, pull_request]
jobs:
build:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
steps:
- uses: actions/checkout@v6
- uses: loonghao/vx@main
with:
tools: 'node@22 uv'
setup: 'true'
cache: 'true'
- run: vx node --version
- run: vx npm test
Action Inputs
| Input |
Default |
Description |
version |
latest |
vx version to install |
github-token |
${{ github.token }} |
GitHub token for API requests |
tools |
'' |
Space-separated tools to pre-install |
cache |
true |
Enable caching of ~/.vx directory |
cache-key-prefix |
vx-tools |
Custom prefix for cache key |
setup |
false |
Run vx setup --ci for vx.toml projects |
Action Outputs
| Output |
Description |
version |
The installed vx version |
cache-hit |
Whether the cache was hit |
Container Image Support
vx also provides a container image for containerized workflows, and it can be consumed from Podman-compatible environments:
# Use vx as base image
FROM ghcr.io/loonghao/vx:latest
# Tools are auto-installed on first use
RUN vx node --version
RUN vx uv pip install mypackage
Multi-stage Build with vx
FROM ghcr.io/loonghao/vx:latest AS builder
RUN vx node --version && vx npm ci && vx npm run build
FROM nginx:alpine
COPY --from=builder /home/vx/dist /usr/share/nginx/html
GitHub Actions Container Jobs
jobs:
build:
runs-on: ubuntu-latest
container:
image: ghcr.io/loonghao/vx:latest
steps:
- uses: actions/checkout@v6
- run: vx node --version
- run: vx npm test
1---2name: vx-usage3description: "Teaches AI agents how to use vx, the universal dev tool manager. Use when the project has vx.toml or .vx/, or when the user mentions vx, tool version management, or cross-platform setup. vx auto-manages Node.js, Python, Go, Rust, and 105 tools via Starlark DSL providers. Also covers MCP integration patterns and GitHub Actions."4metadata:5 source: https://skillmd.com/skills/loonghao/vx-usage6---78# VX - Universal Development Tool Manager910> **One-sentence summary**: vx = prefix any dev tool command with `vx` → it auto-installs the tool and runs it.1112vx is a universal development tool manager that automatically installs and manages13development tools (Node.js, Python/uv, Go, Rust, etc.) with zero configuration.1415## Core Concept1617Instead of requiring users to manually install tools, prefix any command with `vx`:1819```bash20vx node --version # Auto-installs Node.js if needed21vx uv pip install x # Auto-installs uv if needed22vx go build . # Auto-installs Go if needed23vx cargo build # Auto-installs Rust if needed24vx just test # Auto-installs just if needed25```2627vx is fully transparent - same commands, same arguments, just add `vx` prefix.2829## Essential Commands3031### Tool Execution (most common)32```bash33vx <tool> [args...] # Run any tool (auto-installs if missing)34vx node app.js # Run Node.js35vx python script.py # Run Python (via uv)36vx npm install # Run npm37vx npx create-react-app app # Run npx38vx cargo test # Run cargo39vx just build # Run just (task runner)40vx git status # Run git41```4243### Tool Management44```bash45vx install node@22 # Install specific version46vx install uv go rust # Install multiple tools at once47vx list # List all available tools48vx list --installed # List installed tools only49vx versions node # Show available versions50vx switch node@20 # Switch active version51vx uninstall go@1.21 # Remove a version52```5354### Project Management55```bash56vx init # Initialize vx.toml for project57vx sync # Install all tools from vx.toml58vx setup # Full project setup (sync + hooks)59vx dev # Enter dev environment with all tools60vx run test # Run project scripts from vx.toml61vx check # Verify tool constraints62vx lock # Generate vx.lock for reproducibility63```6465### Environment & Config66```bash67vx env list # List environments68vx config show # Show configuration69vx cache info # Show cache usage70vx search <query> # Search available tools71vx info # System info and capabilities72```7374## Project Configuration (vx.toml)7576Projects use `vx.toml` in the root directory:7778```toml79[tools]80node = "22" # Major version81go = "1.22" # Minor version82uv = "latest" # Always latest83rust = "1.80" # Specific version84just = "*" # Any version8586[scripts]87dev = "npm run dev"88test = "cargo test"89lint = "npm run lint && cargo clippy"90build = "just build"9192[hooks]93pre_commit = ["vx run lint"]94post_setup = ["npm install"]95```9697## Using `--with` for Multi-Runtime9899When a command needs additional runtimes available:100101```bash102vx --with bun node app.js # Node.js + Bun in PATH103vx --with deno npm test # npm + Deno available104```105106## Package Aliases107108vx supports **package aliases** — short commands that automatically route to ecosystem packages:109110```bash111# These are equivalent:112vx vite # Same as: vx npm:vite113vx vite@5.0 # Same as: vx npm:vite@5.0114vx rez # Same as: vx uv:rez115vx pre-commit # Same as: vx uv:pre-commit116vx meson # Same as: vx uv:meson117vx release-please # Same as: vx npm:release-please118```119120**Benefits**:121- Simpler commands without remembering ecosystem prefixes122- Automatic runtime dependency management (node/python installed as needed)123- Respects project `vx.toml` version configuration124125**Available Aliases**:126| Short Command | Equivalent | Ecosystem |127|--------------|------------|-----------|128| `vx vite` | `vx npm:vite` | npm |129| `vx release-please` | `vx npm:release-please` | npm |130| `vx rez` | `vx uv:rez` | uv |131| `vx pre-commit` | `vx uv:pre-commit` | uv |132| `vx meson` | `vx uv:meson` | uv |133134## Companion Tool Environment Injection135136When `vx.toml` includes tools like MSVC, vx automatically injects discovery environment variables into **all** subprocess environments. This allows any tool needing a C/C++ compiler to discover the vx-managed installation.137138```toml139# vx.toml — MSVC env vars injected for ALL tools140[tools]141node = "22"142cmake = "3.28"143rust = "1.82"144145[tools.msvc]146version = "14.42"147os = ["windows"]148```149150Now tools like node-gyp, CMake, Cargo (cc crate) automatically find MSVC:151152```bash153# node-gyp finds MSVC via VCINSTALLDIR154vx npx node-gyp rebuild155156# CMake discovers the compiler157vx cmake -B build -G "Ninja"158159# Cargo cc crate finds MSVC for C dependencies160vx cargo build161```162163**Injected Environment Variables** (MSVC example):164| Variable | Purpose |165|----------|---------|166| `VCINSTALLDIR` | VS install path (node-gyp, CMake) |167| `VCToolsInstallDir` | Exact toolchain path |168| `VX_MSVC_ROOT` | vx MSVC root path |169170## MSVC Build Tools (Windows)171172Microsoft Visual C++ compiler for Windows development:173174```bash175# Install MSVC Build Tools176vx install msvc@latest177vx install msvc 14.40 # Specific version178179# Using MSVC tools via namespace180vx msvc cl main.cpp -o main.exe181vx msvc link main.obj182vx msvc nmake183184# Direct aliases185vx cl main.cpp # Same as: vx msvc cl186vx nmake # Same as: vx msvc nmake187188# Version-specific usage189vx msvc@14.40 cl main.cpp190```191192**Available MSVC Tools**:193| Tool | Command | Description |194|------|---------|-------------|195| cl | `vx msvc cl` | C/C++ compiler |196| link | `vx msvc link` | Linker |197| lib | `vx msvc lib` | Library manager |198| nmake | `vx msvc nmake` | Make utility |199200## Supported Tools (114 Providers)201202| Category | Tools |203|----------|-------|204| **JavaScript** | node, npm, npx, bun, deno, pnpm, yarn, vite, nx, turbo |205| **JS Tooling** | oxlint, biome |206| **Python** | uv, uvx, python, pip, ruff, maturin, pre-commit |207| **Rust** | cargo, rustc, rustup |208| **Go** | go, gofmt, gws |209| **System/CLI** | git, bash, curl, pwsh, jq, yq, fd, bat, ripgrep, fzf, starship, jj, sd, eza, dust, duf, xh, atuin, zoxide, tealdeer, gping, delta, hyperfine, watchexec, bottom |210| **TUI/Terminal** | helix, yazi, zellij, lazygit, lazydocker, k9s |211| **Build Tools** | just, task, cmake, ninja, make, meson, xmake, protoc, conan, vcpkg, spack |212| **DevOps** | kubectl, helm, podman, terraform, hadolint, dagu, actionlint |213| **Security** | gitleaks, trivy |214| **Cloud CLI** | awscli, azcli, gcloud |215| **.NET** | dotnet, msbuild, nuget |216| **C/C++** | msvc, llvm, nasm, ccache, buildcache, sccache, rcedit |217| **Media** | ffmpeg, imagemagick |218| **Java** | java |219| **AI** | ollama, openclaw |220| **Other Langs** | zig |221| **Container** | dive |222| **Config Mgmt** | chezmoi, mise |223| **Package Managers** | brew, choco, winget |224| **Misc** | gh, prek, actrun, wix, vscode, xcodebuild, systemctl, release-please, rez, 7zip, trippy |225226## Provider System (Starlark DSL)227228All 114 providers are defined using **provider.star** (Starlark DSL) — a declarative, zero-compilation approach. Each provider lives in `crates/vx-providers/<name>/provider.star`.229230vx uses a **two-phase execution model** (inspired by Buck2):2311. **Analysis Phase (Starlark)**: `provider.star` runs as pure computation, returning descriptor dicts. No I/O.2322. **Execution Phase (Rust)**: The Rust runtime interprets descriptors for actual downloads, installs, and process execution.233234### How to add a new tool235236```starlark237# crates/vx-providers/mytool/provider.star238load("@vx//stdlib:provider.star", "runtime_def", "github_permissions")239load("@vx//stdlib:provider_templates.star", "github_rust_provider")240241name = "mytool"242description = "My awesome tool"243ecosystem = "custom"244245runtimes = [runtime_def("mytool", aliases=["mt"])]246permissions = github_permissions()247248# Use a template — covers 90% of tools249_p = github_rust_provider("owner", "mytool",250 asset = "mytool-{vversion}-{triple}.{ext}")251fetch_versions = _p["fetch_versions"]252download_url = _p["download_url"]253install_layout = _p["install_layout"]254store_root = _p["store_root"]255get_execute_path = _p["get_execute_path"]256environment = _p["environment"]257```258259### Available templates260261| Template | Use case | Example |262|----------|----------|---------|263| `github_rust_provider` | Rust tools on GitHub (most common) | ripgrep, fd, bat, just, uv |264| `github_go_provider` | Go tools on GitHub (goreleaser style) | gh, task |265| `github_binary_provider` | Single binary download (no archive) | kubectl |266| `system_provider` | System package manager only | 7zip |267268### Template Placeholders269270| Placeholder | Rust template | Go template | Description |271|-------------|---------------|-------------|-------------|272| `{version}` | ✓ | ✓ | Version number (e.g., "1.0.0") |273| `{vversion}` | ✓ | — | With v-prefix (e.g., "v1.0.0") |274| `{triple}` | ✓ | — | Rust target triple (e.g., "x86_64-unknown-linux-musl") |275| `{os}` | — | ✓ | Go GOOS (linux, darwin, windows) |276| `{arch}` | — | ✓ | Go GOARCH (amd64, arm64) |277| `{ext}` | ✓ | ✓ | Archive extension (zip/tar.gz) |278| `{exe}` | ✓ | ✓ | Executable suffix (.exe/"") |279280### Starlark Standard Library (14 modules)281282Located in `crates/vx-starlark/stdlib/`. The main entry point is `provider.star` which re-exports everything:283284```starlark285# Import everything from the unified facade286load("@vx//stdlib:provider.star",287 "runtime_def", "bundled_runtime_def", "dep_def",288 "github_permissions", "platform_map",289 "env_set", "env_prepend",290 "archive_layout", "binary_layout")291```292293Key modules:294- `provider.star` — Unified facade (re-exports all)295- `runtime.star` — `runtime_def`, `bundled_runtime_def`, `dep_def`296- `platform.star` — `platform_map`, `platform_select`, `rust_triple`, `go_os_arch`297- `env.star` — `env_set`, `env_prepend`, `env_append`, `env_unset`298- `layout.star` — `archive_layout`, `binary_layout`, `bin_subdir_layout`, hooks299- `provider_templates.star` — High-level templates (4 templates)300- `permissions.star` — `github_permissions`, `system_permissions`301- `system_install.star` — `winget_install`, `brew_install`, `apt_install`302303## Important Rules for AI Agents3043051. **Always use `vx` prefix** when running tools in vx-managed projects3062. **Use `vx just`** instead of `just` for task runner commands3073. **Use `vx npm`** instead of `npm` directly3084. **Use `vx cargo`** instead of `cargo` directly3095. **Check `vx.toml`** first to understand project tool requirements3106. **Use `vx run <script>`** for project-defined scripts3117. **Never suggest manual tool installation** - vx handles it automatically3128. Commands like `vx install` are for explicit pre-installation; normal usage auto-installs3139. **Use correct terminology**: Runtime (not Tool), Provider (not Plugin), provider.star (not provider config)31410. **Provider development**: New tools are added via `provider.star` Starlark DSL in `crates/vx-providers/<name>/`31511. **Tests go in `tests/` dirs** — never inline `#[cfg(test)]` in source files316317## Version Resolution Priority318319vx resolves tool versions in this order (highest to lowest):3203211. **Command-line override**: `vx node@22 app.js`3222. **Project vx.toml**: `[tools] node = "22"`3233. **Parent directory vx.toml** (traverses up to root)3244. **User global config**: `~/.config/vx/config.toml`3255. **Provider default**: latest stable version326327## MCP Integration328329vx is **MCP-ready** — replace `npx`/`uvx` with `vx` in MCP server configurations.330This eliminates the "install Node.js/Python first" requirement for all MCP servers.331332### Configuration Pattern333334```json335{336 "mcpServers": {337 "example-server": {338 "command": "vx",339 "args": ["npx", "-y", "@example/mcp-server@latest"]340 },341 "python-server": {342 "command": "vx",343 "args": ["uvx", "some-python-mcp-server@latest"]344 }345 }346}347```348349### Real-World MCP Examples350351```json352{353 "mcpServers": {354 "filesystem": {355 "command": "vx",356 "args": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]357 },358 "github": {359 "command": "vx",360 "args": ["npx", "-y", "@modelcontextprotocol/server-github"],361 "env": { "GITHUB_TOKEN": "<token>" }362 },363 "sqlite": {364 "command": "vx",365 "args": ["uvx", "mcp-server-sqlite", "--db-path", "/path/to/db.sqlite"]366 }367 }368}369```370371### Migration Pattern372373| Original | vx-powered |374|----------|------------|375| `"command": "npx"` | `"command": "vx", "args": ["npx", ...]` |376| `"command": "uvx"` | `"command": "vx", "args": ["uvx", ...]` |377| `"command": "node"` | `"command": "vx", "args": ["node", ...]` |378| `"command": "python"` | `"command": "vx", "args": ["python", ...]` |379| `"command": "bun"` | `"command": "vx", "args": ["bun", ...]` |380381### Benefits for AI Agents382383- **Zero-config**: No need to check if Node.js/Python is installed before starting MCP servers384- **Version consistency**: MCP servers always use the version specified in `vx.toml`385- **Cross-platform**: Same MCP config works on Windows, macOS, and Linux386- **CI/CD ready**: MCP servers in CI pipelines just work with vx387388## GitHub Actions Integration389390vx provides a GitHub Action (`action.yml`) for CI/CD workflows. Use it in `.github/workflows/` files:391392### Basic Usage393394```yaml395- uses: loonghao/vx@main396 with:397 version: 'latest' # vx version (default: latest)398 github-token: ${{ secrets.GITHUB_TOKEN }}399```400401### Pre-install Tools402403```yaml404- uses: loonghao/vx@main405 with:406 tools: 'node go uv' # Space-separated tools to pre-install407 cache: 'true' # Enable tool caching (default: true)408```409410### Project Setup (vx.toml)411412```yaml413- uses: loonghao/vx@main414 with:415 setup: 'true' # Run `vx setup --ci` for vx.toml projects416```417418### Full Example419420```yaml421name: CI422on: [push, pull_request]423424jobs:425 build:426 runs-on: ${{ matrix.os }}427 strategy:428 matrix:429 os: [ubuntu-latest, macos-latest, windows-latest]430431 steps:432 - uses: actions/checkout@v6433434 - uses: loonghao/vx@main435 with:436 tools: 'node@22 uv'437 setup: 'true'438 cache: 'true'439440 - run: vx node --version441 - run: vx npm test442```443444### Action Inputs445446| Input | Default | Description |447|-------|---------|-------------|448| `version` | `latest` | vx version to install |449| `github-token` | `${{ github.token }}` | GitHub token for API requests |450| `tools` | `''` | Space-separated tools to pre-install |451| `cache` | `true` | Enable caching of ~/.vx directory |452| `cache-key-prefix` | `vx-tools` | Custom prefix for cache key |453| `setup` | `false` | Run `vx setup --ci` for vx.toml projects |454455### Action Outputs456457| Output | Description |458|--------|-------------|459| `version` | The installed vx version |460| `cache-hit` | Whether the cache was hit |461462## Container Image Support463464vx also provides a container image for containerized workflows, and it can be consumed from Podman-compatible environments:465466467```dockerfile468# Use vx as base image469FROM ghcr.io/loonghao/vx:latest470471# Tools are auto-installed on first use472RUN vx node --version473RUN vx uv pip install mypackage474```475476### Multi-stage Build with vx477478```dockerfile479FROM ghcr.io/loonghao/vx:latest AS builder480RUN vx node --version && vx npm ci && vx npm run build481482FROM nginx:alpine483COPY --from=builder /home/vx/dist /usr/share/nginx/html484```485486### GitHub Actions Container Jobs487488```yaml489jobs:490 build:491 runs-on: ubuntu-latest492 container:493 image: ghcr.io/loonghao/vx:latest494 steps:495 - uses: actions/checkout@v6496 - run: vx node --version497 - run: vx npm test498```