Environment Variables

vx respects various environment variables for configuration and behavior.

vx Configuration

Variable	Description	Default
VX_HOME	Override vx data directory	Platform-specific
VX_CONFIG_DIR	Override config directory	Platform-specific
VX_CACHE_DIR	Override cache directory	Platform-specific
VX_AUTO_INSTALL	Enable/disable auto-install	true
VX_VERBOSE	Enable verbose output	false
VX_DEBUG	Enable debug output	false
VX_ENV	Current environment name	default

CDN Acceleration

vx supports CDN acceleration for downloads via turbo-cdn, which can significantly improve download speeds especially in regions with slow access to GitHub (e.g., China).

How It Works

When CDN acceleration is enabled:

1. Download URLs are automatically optimized to use the best available CDN mirror
2. Progress display shows [CDN] indicator when CDN is active
3. Falls back to original URL if CDN optimization fails

Enabling CDN Acceleration

CDN acceleration is enabled by default when vx is compiled with the cdn-acceleration feature. The official release binaries include this feature.

Supported Sources

CDN acceleration works with:

• GitHub Releases (e.g., Node.js, Go, Zig, Rust tools)
• GitHub raw content
• npm registry
• PyPI packages
• And more (via turbo-cdn's mirror network)

Data Directories

Default Locations

Platform	Data	Config	Cache
Linux	~/.local/share/vx	~/.config/vx	~/.cache/vx
macOS	~/Library/Application Support/vx	~/.config/vx	~/Library/Caches/vx
Windows	%LOCALAPPDATA%\vx	%APPDATA%\vx	%LOCALAPPDATA%\vx\cache

Override Directories

# Override all vx directories
export VX_HOME=/custom/path/vx

# Override specific directories
export VX_CONFIG_DIR=/custom/config
export VX_CACHE_DIR=/custom/cache

Behavior Control

Auto-Install

# Disable auto-install
export VX_AUTO_INSTALL=false

# Enable auto-install (default)
export VX_AUTO_INSTALL=true

Verbose Output

# Enable verbose output
export VX_VERBOSE=true

# Or use flag
vx --verbose node --version

Debug Output

# Enable debug output
export VX_DEBUG=true

# Or use flag
vx --debug node --version

Environment Management

Current Environment

# Set current environment
export VX_ENV=my-env

# Check current environment
echo $VX_ENV

Environment Directory

When an environment is active:

VX_ENV=my-env
VX_ENV_DIR=/home/user/.local/share/vx/envs/my-env

Tool-Specific Variables

Node.js

NODE_ENV=production vx node server.js

Go

GOPROXY=direct vx go get github.com/user/repo
CGO_ENABLED=0 vx go build

Rust

CARGO_HOME=/custom/cargo vx cargo build
RUSTFLAGS="-C target-cpu=native" vx cargo build --release

Python/UV

UV_CACHE_DIR=/custom/cache vx uv pip install requests

Shell Integration

When shell integration is enabled, these variables are set automatically:

# Added to PATH
PATH="/home/user/.local/share/vx/envs/default:$PATH"

# Environment tracking
VX_ENV="default"
VX_ENV_DIR="/home/user/.local/share/vx/envs/default"

CI/CD Usage

GitHub Actions

env:
  VX_AUTO_INSTALL: true
  VX_VERBOSE: true

steps:
  - run: vx setup
  - run: vx run test

GitLab CI

variables:
  VX_AUTO_INSTALL: "true"
  VX_HOME: "$CI_PROJECT_DIR/.vx"

script:
  - vx setup
  - vx run test

Troubleshooting

Check Current Settings

# Show all vx-related environment variables
env | grep VX_

# Show effective configuration
vx config show

Reset Environment

# Unset all vx variables
unset VX_HOME VX_ENV VX_AUTO_INSTALL VX_VERBOSE VX_DEBUG