Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vers.sh/llms.txt

Use this file to discover all available pages before exploring further.

vers deploy creates a VM for a GitHub repository: it clones the repo, installs dependencies, builds, and runs the project, all in one call. The deploy runs asynchronously — the command returns immediately with the project and VM IDs so you can follow up with vers status, vers connect, or vers info.

​
Synopsis

vers deploy <owner/repo>
vers deploy <owner/repo> --branch develop
vers deploy <owner/repo> --name my-project \
  --install "npm install" \
  --build   "npm run build" \
  --run     "npm start"
vers deploy <owner/repo> --working-dir packages/web
vers deploy <owner/repo> --wait --format json
Prerequisites
  • The Vers GitHub App must be installed on the repository’s organization.
  • Your API key’s organization must match the GitHub App installation.

​
Options

OptionDescription
--nameProject name (defaults to the repository name)
--branchGit branch to deploy (defaults to the repo’s default branch)
--installInstall command (e.g. npm install, pip install -r requirements.txt)
--buildBuild command (e.g. npm run build)
--runRun command (e.g. npm start)
--working-dirWorking directory relative to the repo root (useful for monorepos)
--waitBlock until the VM reports Running before returning
--format jsonMachine-readable output

​
Examples

​
Deploy the default branch

vers deploy hdresearch/my-app

​
Deploy a specific branch with explicit commands

vers deploy hdresearch/my-app \
  --branch develop \
  --install "pnpm install" \
  --build "pnpm build" \
  --run "pnpm start"

​
Deploy from a monorepo

vers deploy acme/platform --working-dir services/api

​
Wait for the VM and parse the response

vers deploy hdresearch/my-app --wait --format json \
  | jq '{project: .project_id, vm: .vm_id}'

​
How it works

1

Repository lookup

The orchestrator resolves <owner/repo> via the Vers GitHub App installation attached to your organization.
2

VM provisioning

A fresh root VM is created and returned immediately.
3

Clone + install + build + run

The orchestrator clones the repo, runs --install, --build, and --run in sequence, respecting --working-dir.
4

Follow-up

Use vers status <vm-id> to watch state, vers connect <vm-id> to SSH in, or vers info <vm-id> for networking details.

​
Common Patterns

​
Deploy a monorepo subproject

vers deploy acme/platform \
  --working-dir services/api \
  --install "pnpm install" \
  --build "pnpm build" \
  --run "pnpm start"

​
Async deploy, then tail logs

Deploy returns immediately with a VM id; watch the boot from a second command: 
VM=$(vers deploy hdresearch/my-app --format json | jq -r .vm_id)
vers execute "$VM" -- journalctl -fu app --no-pager

​
Deploy a specific branch for a hotfix

vers deploy hdresearch/my-app --branch hotfix/payment-bug --wait

​
See also

  • vers run — start a VM from your local vers.toml
  • vers build — build a commit from a Dockerfile
  • vers repo — manage Vers repositories (different concept: groups of commits)