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

> Deploy a GitHub repository to a new Vers project — clone, install, build, run.

`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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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
```

<Info>
  **Prerequisites**

  * The Vers GitHub App must be installed on the repository's organization.
  * Your API key's organization must match the GitHub App installation.
</Info>

## Options

| Option          | Description                                                             |
| --------------- | ----------------------------------------------------------------------- |
| `--name`        | Project name (defaults to the repository name)                          |
| `--branch`      | Git branch to deploy (defaults to the repo's default branch)            |
| `--install`     | Install command (e.g. `npm install`, `pip install -r requirements.txt`) |
| `--build`       | Build command (e.g. `npm run build`)                                    |
| `--run`         | Run command (e.g. `npm start`)                                          |
| `--working-dir` | Working directory relative to the repo root (useful for monorepos)      |
| `--wait`        | Block until the VM reports Running before returning                     |
| `--format json` | Machine-readable output                                                 |

## Examples

### Deploy the default branch

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers deploy hdresearch/my-app
```

### Deploy a specific branch with explicit commands

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers deploy hdresearch/my-app \
  --branch develop \
  --install "pnpm install" \
  --build "pnpm build" \
  --run "pnpm start"
```

### Deploy from a monorepo

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers deploy acme/platform --working-dir services/api
```

### Wait for the VM and parse the response

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers deploy hdresearch/my-app --wait --format json \
  | jq '{project: .project_id, vm: .vm_id}'
```

## How it works

<Steps>
  <Step title="Repository lookup">
    The orchestrator resolves `<owner/repo>` via the Vers GitHub App installation attached to your organization.
  </Step>

  <Step title="VM provisioning">
    A fresh root VM is created and returned immediately.
  </Step>

  <Step title="Clone + install + build + run">
    The orchestrator clones the repo, runs `--install`, `--build`, and `--run` in sequence, respecting `--working-dir`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Common Patterns

### Deploy a monorepo subproject

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers deploy hdresearch/my-app --branch hotfix/payment-bug --wait
```

## See also

* [vers run](/cli-reference/run) — start a VM from your local `vers.toml`
* [vers build](/cli-reference/build) — build a commit from a Dockerfile
* [vers repo](/cli-reference/repo) — manage Vers repositories (different concept: groups of commits)