vcvm/README.md

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

# 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](https://esbuild.github.io/) 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

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

```bash
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 <sandbox-id>
   \`\`\`

## 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](https://github.com/vadimdemedes/ink) for beautiful CLI interfaces
- Uses [@vercel/sandbox](https://vercel.com/docs/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:

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