Vercel VM Factory

Create a tiny Vercel Container deployment: copy wsterm from ghcr.io/v1xingyue/ws-shell:v1.8.alpine into a selected VM image, then deploy with Vercel CLI.

npx vercel-vm-factory create \
  --vm-image ubuntu \
  --shell /bin/bash \
  --tools nodejs,codex \
  --project ws-shell-ubuntu \
  --auth-mode basic \
  --auth-user admin \
  --auth-password change-me

GitHub OAuth is optional:

npx vercel-vm-factory create \
  --auth-mode github \
  --client-id YOUR_GITHUB_CLIENT_ID \
  --client-secret YOUR_GITHUB_CLIENT_SECRET \
  --github-userid 12345678

Run without flags for prompts:

npx vercel-vm-factory create

The prompt walks through VM image, Vercel team, project, shell, optional preinstalled tools, MCP token, and authentication. Teams are loaded from vercel teams list --format json; choose Default to use the current Vercel CLI scope. For list prompts, enter either names or numbers; tool choices can be comma-separated, for example 1,3 or nodejs,claude-code.

Check local setup:

npx vercel-vm-factory doctor

The script checks vercel --version and vercel whoami; if you are not logged in, it runs vercel login.

View deployments:

npx vercel-vm-factory list
npx vercel-vm-factory list ws-shell-ubuntu

Delete a VM project:

npx vercel-vm-factory delete ws-shell-ubuntu

ls/view alias list; rm aliases delete. list and delete use the saved project when no project is passed.

Use --help to show all flags.

Common flags:

• --vm-image alpine|ubuntu|debian|IMAGE
• --shell /bin/bash|/bin/zsh|/bin/sh
• --tools nodejs,codex,claude-code
• --project NAME
• --scope TEAM_SLUG to skip team selection
• --auth-mode basic|github|both|none
• --background-server-url URL
• --mcp-token TOKEN|random
• --dry-run

Default project names use the selected VM image plus a random word, for example ubuntu-nova. Entered auth and MCP values are reused from ~/.vercel-vm-factory/defaults.json; press Enter to keep the placeholder value or skip an empty one.

The generated project contains only Dockerfile.vercel.

--background-server-url sets BACKGROUND_SERVER_URL, the proxied real web app target. The MCP prompt lets you generate a random token, enter one manually, or disable MCP. --mcp-token sets MCP_TOKEN; MCP clients can use Authorization: Bearer TOKEN or /console/vm/mcp?token=TOKEN.

Use --mcp-token random to generate a 24-byte URL-safe token. generate and auto are accepted aliases. The CLI prints the generated token and the full /console/vm/mcp?token=... URL after deploy.

CLI mapping:

• Vercel Team -> loaded from vercel teams list --format json; --scope TEAM_SLUG skips the selector
• Project Name -> --project x-shell
• Application Preset -> patched through Vercel API as framework=container
• Root Directory -> generated project directory

VM image presets:

• alpine -> alpine:3.23
• ubuntu -> ubuntu:24.04
• debian -> debian:13-slim

Shell options:

• /bin/bash
• /bin/zsh
• /bin/sh

Choosing bash or zsh adds the matching package to the generated Dockerfile when the VM image does not already include it. Choosing zsh also installs oh-my-zsh.

Generated shell setup examples:

• Alpine + /bin/zsh: installs zsh curl git ca-certificates, clones oh-my-zsh into /root/.oh-my-zsh, and writes /root/.zshrc.
• Ubuntu/Debian + /bin/bash: installs bash with apt-get.
• /bin/sh: no extra shell package is installed.

The generated Dockerfile sets HOME=/root and SHELL to the selected shell path.

Preinstall tools:

• nodejs
• codex
• claude-code

Choosing codex or claude-code also installs Node.js/npm.

Generated tool setup examples:

• --tools nodejs: installs nodejs npm
• --tools codex: installs nodejs npm, then npm install -g @openai/codex
• --tools claude-code: installs nodejs npm, then npm install -g @anthropic-ai/claude-code
• --tools codex,claude-code: installs both CLIs

Custom VM image:

npx vercel-vm-factory create --vm-image fedora:42 --project ws-shell-fedora

Before deploying, set the GitHub OAuth callback URL to:

https://PROJECT.vercel.app/auth/github/callback

For example, if --project x-shell, set:

https://x-shell.vercel.app/auth/github/callback

GitHub OAuth fields:

• Auth mode -> --auth-mode basic|github|both|none
• Username -> --auth-user
• Password -> --auth-password
• Client ID -> --client-id
• Client Secret -> --client-secret
• Numeric GitHub user ID -> --github-userid

Get your numeric user ID:

https://api.github.com/users/YOUR_LOGIN

The callback URL must match exactly. If you deploy under another project name or custom domain, update the GitHub OAuth App or pass --redirect-url.

Use --dry-run to generate files without deploying.