vm-cli

One-command path to fresh, isolated Linux micro-VMs on Vercel.

Features

• 🚀 Quick Start: Spin up development environments in seconds
• 🔐 SSH Access: Direct SSH connection to your sandbox environments
• 🛠 Multiple Runtimes: Support for Node.js and Python environments
• 📊 Management: List, monitor, and control your active sandboxes
• ⚡ Port Forwarding: Expose multiple ports for web apps and services

Build System

This project uses esbuild for fast and efficient builds. The build system is configured in build.mjs and provides:

• Lightning-fast builds: Typically completes in under 20ms
• Development mode with watch: Automatically rebuilds on file changes
• Production optimizations: Minification and tree-shaking for smaller bundles
• Source maps: For easier debugging in development
• ESM output: Modern ES modules with proper Node.js compatibility

Build Commands

# Development build
npm run build

# Production build (minified)
npm run build:prod

# Watch mode for development
npm run dev

# Type checking (without emitting files)
npm run type-check

Build Features

• Bundle size: ~10KB minified (production) vs ~31KB (development)
• External dependencies: Dependencies are marked as external to keep bundle size small
• Automatic shebang: The CLI executable is automatically created with proper permissions
• Debounced watch mode: Prevents redundant builds during rapid file changes

Installation

npm install -g vm-cli

Quick Start

1. Authenticate with Vercel: ```bash vercel link vercel env pull ```

2. Start a new sandbox: ```bash vm start ```

3. SSH into your environment: ```bash vm ssh ```

Commands

vm start

Start a new sandbox environment with SSH server.

Options:

• --runtime, -r: Runtime environment (node22, python3.13)
• --ports, -p: Comma-separated list of ports to expose (default: 22,3000)
• --timeout, -t: Sandbox timeout (default: 30m, max: 45m)

Examples: ```bash vm start # Default: node22, ports 22,3000 vm start --runtime python3.13 # Python environment
vm start --ports 3000,8080 --timeout 1h # Custom ports and timeout ```

vm list

Show all active sandboxes with their connection details.

vm ssh <sandbox-id>

Connect to a running sandbox via SSH.

vm status <sandbox-id>

Show detailed status information for a specific sandbox.

vm stop <sandbox-id>

Stop and remove a running sandbox.

Authentication

vcvm supports two authentication methods:

1. Vercel OIDC Token (Recommended)

```bash vercel link # Link to your Vercel project vercel env pull # Download authentication token ```

2. Access Token

Set environment variables: ```bash export VERCEL_TOKEN="your-token" export VERCEL_TEAM_ID="your-team-id"
export VERCEL_PROJECT_ID="your-project-id" ```

Use Cases

• Development Environments: Quickly spin up isolated dev environments
• Code Testing: Test applications in clean, reproducible environments
• Collaboration: Share development environments with team members
• CI/CD: Use in automated workflows for testing and deployment
• Learning: Experiment with new technologies without local setup

Technical Details

• Built with Ink for beautiful CLI interfaces
• Uses @vercel/sandbox for environment management [^1][^2]
• Supports up to 8 vCPUs and 45-minute runtime limits [^4]
• Automatic SSH server setup with password-less authentication
• Local storage for sandbox management and connection details

Publishing

This package is automatically published to npm when a new release is created on GitHub.

Automated Release Process

1. Update the version in package.json
2. Commit your changes: git commit -am "chore: release v1.0.1"
3. Create a git tag: git tag v1.0.1
4. Push changes and tag: git push && git push --tags
5. Create a release on GitHub - this will trigger the npm publish workflow

Manual Publishing

If you need to publish manually:

# Build the project
npm run build:prod

# Publish to npm
npm publish --access public

Setting up NPM Token

For the GitHub Action to work, you need to:

1. Create an npm access token at https://www.npmjs.com/settings/YOUR_USERNAME/tokens
2. Add it as a secret named NPM_TOKEN in your GitHub repository settings

Contributing

Contributions welcome! Please read our contributing guidelines and submit pull requests.

License

MIT License - see LICENSE file for details.