Skip to content
Back to search

provr

MarketplaceWorks with Claude CodeGitHub

Marketplace for the provr Claude Code plugin: start and manage provr preview environments.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/divait--provr/badge.svg)](/listings/divait--provr)

HTML

<a href="/listings/divait--provr"><img src="/api/listings/divait--provr/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

With Go (1.25 or newer):

go install github.com/divait/provr/cmd/provr@v0.1.0

`@latest` works too once a release is published. Or download a release binary:

1. Download the archive for your platform (Linux or macOS, amd64 or arm64; named like `provr_<version>_<os>_<arch>.tar.gz`) from the [GitHub Releases](https://github.com/divait/provr/releases) page. 2. Verify it against `checksums.txt` from the same release, for example `sha256sum --ignore-missing -c checksums.txt` (on macOS: `shasum -a 256 -c checksums.txt --ignore-missing`). 3. Unpack it and put `provr` on your `PATH`.

Check the install with `provr version`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines
  1. {
  2. "name": "provr",
  3. "owner": {
  4. "name": "divait",
  5. "url": "https://github.com/divait"
  6. },
  7. "description": "Marketplace for the provr Claude Code plugin: start and manage provr preview environments.",
  8. "plugins": [
  9. {
  10. "name": "provr",
  11. "source": "./integrations/claude",
  12. "description": "Start and manage provr preview environments from Claude Code."
  13. }
  14. ]
  15. }
README.md · README · 263 lines
  1. # provr
  2. **Isolated, full-stack preview environments for coding agents, on your own GCP project.**
  3. provr lets an agent (Claude Code, Codex, or any MCP client) or a human run the
  4. current git worktree as a complete Docker Compose stack on a remote host. It
  5. returns a private URL, runs tests against the stack, and tears it down
  6. afterwards. Every preview expires on its own.
  7. > **Status: pre-alpha.** `provr init` (GCP project and Tailscale setup),
  8. > `provr.yaml` loading, `doctor`, and the preview commands (`up`, `exec`,
  9. > `logs`, `ls`, `down`), `gc`, and the MCP server (`provr mcp`) work. The MVP is being built now; see [Roadmap](#roadmap).
  10. ## Why
  11. When several agents work in parallel git worktrees on one dev server, they
  12. compete for ports, CPU and RAM as soon as they try to run what they built. So
  13. they either skip testing or test in a messy shared environment.
  14. provr moves each preview to a warm host in GCP:
  15. - **Isolated:** every worktree gets its own compose project, network and
  16. volumes. No port clashes, even when the compose file hard-codes ports and
  17. container names.
  18. - **Built from what's actually in the worktree:** uncommitted changes
  19. included, so agents can test before they commit or open a PR.
  20. - **Private:** hosts have no public IP. Each preview gets its own hostname on
  21. your Tailscale tailnet, which you can open from a laptop or phone.
  22. - **Cleaned up by design:** previews have a TTL (maximum 12 h), idle hosts stop
  23. themselves, and unused hosts are deleted. Cleanup doesn't depend on the agent
  24. that created them.
  25. - **Works with any agent:** a single Go binary that contains both the CLI and
  26. an MCP server.
  27. ## How it works
  28. ```
  29. Dev server (agents in git worktrees) Project's own GCP project
  30. ┌───────────────────────────────────┐ ┌─────────────────────────────────────┐
  31. │ agent ─▶ provr (MCP / CLI) │ Tailscale │ preview host (GCE VM, warm Docker) │
  32. │ up · exec · logs · down │ ── SSH ──▶ │ ├─ preview pr-42 (compose + sidecar)┼─▶ pr-42.<tailnet>.ts.net
  33. │ │ + rsync │ └─ preview pr-43 (compose + sidecar)┼─▶ pr-43.<tailnet>.ts.net
  34. └───────────────────────────────────┘ └─────────────────────────────────────┘
  35. your phone / laptop ── tailnet ──▶ preview URLs
  36. ```
  37. 1. `provr up` finds or starts the project's host (or creates one).
  38. 2. It copies the worktree with rsync, then places your gitignored secrets on
  39. top of it from a local `secrets_dir`.
  40. 3. It generates a compose **override** that resets host ports and
  41. `container_name`s and adds a Tailscale sidecar. Your compose files are
  42. never edited.
  43. 4. It runs `docker compose up --build`, waits for the healthcheck, and returns
  44. the URLs and the expiry time.
  45. ## Usage
  46. ```bash
  47. provr init --gcp-project my-previews --zone us-central1-a # one-time project setup (works now)
  48. provr doctor # check the repo's compose setup
  49. provr up # preview the current worktree
  50. provr exec <id> --script test # run the project's tests in it
  51. provr logs <id> api
  52. provr ls
  53. provr down <id>
  54. ```
  55. Agents use the same operations as MCP tools through `provr mcp`
  56. (`preview_up`, `preview_exec`, `preview_logs`, `preview_status`,
  57. `preview_list`, `preview_down`).
  58. ### `provr.yaml`
  59. ```yaml
  60. version: 1
  61. project: myapp
  62. gcp:
  63. project: myapp-previews
  64. zone: us-central1-a
  65. host:
  66. machine_type: e2-standard-4
  67. max_previews: 2
  68. compose:
  69. files: [docker-compose.yml]
  70. secrets_dir: ~/.provr/myapp # mirrors repo paths, e.g. configs/env/api.env
  71. expose:
  72. web: 3000
  73. api: 8000
  74. healthcheck:
  75. service: api
  76. path: /health
  77. commands:
  78. test: "docker compose exec -T api pytest"
  79. ttl:
  80. default: 4h
  81. max: 12h
  82. agents:
  83. auto_preview: on_change # or on_request
  84. ```
  85. A commented example with every field is in
  86. [examples/provr.yaml](examples/provr.yaml); the schema is in
  87. [SPEC-002](anton/specs/SPEC-002-project-config/spec.md).
  88. ## Install
  89. With Go (1.25 or newer):
  90. ```bash
  91. go install github.com/divait/provr/cmd/provr@v0.1.0
  92. ```
  93. `@latest` works too once a release is published. Or download a release binary:
  94. 1. Download the archive for your platform (Linux or macOS, amd64 or arm64;
  95. named like `provr_<version>_<os>_<arch>.tar.gz`) from the
  96. [GitHub Releases](https://github.com/divait/provr/releases) page.
  97. 2. Verify it against `checksums.txt` from the same release, for example
  98. `sha256sum --ignore-missing -c checksums.txt` (on macOS:
  99. `shasum -a 256 -c checksums.txt --ignore-missing`).
  100. 3. Unpack it and put `provr` on your `PATH`.
  101. Check the install with `provr version`.
  102. ## Install for Claude Code
  103. 1. Install the binary (see [Install](#install)) and make sure it is on
  104. `PATH`.
  105. 2. Add the plugin inside Claude Code:
  106. ```
  107. /plugin marketplace add divait/provr
  108. /plugin install provr@provr
  109. ```
  110. 3. Export `TS_OAUTH_CLIENT_ID` and `TS_OAUTH_CLIENT_SECRET` in the shell that
  111. starts `claude` (for example in herdr's environment). The plugin never
  112. stores them. Be logged in with `gcloud`; after a re-login, reconnect the
  113. MCP server with `/mcp`.
  114. The plugin runs `provr mcp` and adds a preview skill: when a task changes
  115. code, the agent starts a preview, runs the tests in it, and reports the URLs.
  116. Control this with `agents.auto_preview` in `provr.yaml`:
  117. - `on_change` (recommended, default): start a preview when a task changes code.
  118. - `on_request`: start a preview only when you ask.
  119. See [examples/provr.yaml](examples/provr.yaml).
  120. Release rule: bump `version` in
  121. `integrations/claude/.claude-plugin/plugin.json` together with the release tag
  122. (`v0.1.0` needs `0.1.0`); CI fails a tagged build that disagrees.
  123. ## Requirements (MVP)
  124. - **Dev server:** Linux or macOS with `gcloud`, `git`, `rsync`, Docker with
  125. Compose ≥ 2.24, and Tailscale.
  126. - **Per project:** a dedicated GCP project with billing enabled, and a
  127. Tailscale OAuth client (`TS_OAUTH_CLIENT_ID` / `TS_OAUTH_CLIENT_SECRET`)
  128. that is allowed to use `tag:provr` and has the `auth_keys` and
  129. `devices:core` scopes (`policy_file:read` is optional).
  130. - **Repo:** a working `docker-compose.yml`.
  131. ## Building from source
  132. Requires Go 1.25+.
  133. ```bash
  134. make build # builds bin/provr with version info
  135. make check # gofmt, go vet, golangci-lint, tests (-race), file-length limits
  136. make smoke # builds a binary and checks the CLI behaves as specified
  137. ```
  138. Or without make: `go build -o provr ./cmd/provr`.
  139. ## Live GCE test
  140. `internal/host/gce/live_test.go` (build tag `e2e`) exercises the GCE host
  141. provider against real GCP and Tailscale. It is never part of `go test ./...`
  142. or `make check`. It creates one VM (plus one more if the optional quota or
  143. concurrency checks are enabled) and deletes it afterwards, so it costs a few
  144. minutes of VM time.
  145. Prerequisites:
  146. - `provr init` has been run on the GCP project, so `provr-operator`,
  147. `provr-net`/`provr-subnet` and Cloud NAT exist.
  148. - `gcloud auth login` as a user who can impersonate `provr-operator`.
  149. - A Tailscale OAuth client with the `auth_keys` and `devices:core` scopes, and
  150. a tailnet policy that defines `tag:provr`.
  151. Environment:
  152. | Variable | Required | Meaning |
  153. |----------|----------|---------|
  154. | `PROVR_E2E_GCP_PROJECT` | yes | GCP project id |
  155. | `PROVR_E2E_ZONE` | yes | zone, e.g. `us-central1-a` |
  156. | `TS_OAUTH_CLIENT_ID`, `TS_OAUTH_CLIENT_SECRET` | yes | Tailscale OAuth client |
  157. | `PROVR_E2E_PROJECT` | no | provr project name (default `provr-e2e-tmp`); must not name a real provr project, see below |
  158. | `PROVR_E2E_MACHINE_TYPE` | no | default `e2-standard-2` |
  159. | `PROVR_E2E_QUOTA_MACHINE_TYPE` | no | machine type in a zero-quota family, e.g. `c3-standard-4`; enables the quota check |
  160. | `PROVR_E2E_CONCURRENT` | no | `1` enables the two-parallel-Ensure check |
  161. Run it (it skips when the required variables are missing):
  162. ```sh
  163. make e2e-gce
  164. # or: go test -tags e2e -run TestLive -count=1 -timeout 30m -v ./internal/host/gce
  165. ```
  166. Before it starts, the test deletes `provr-<PROVR_E2E_PROJECT>-1` (and the
  167. `provr-<PROVR_E2E_PROJECT>q-1` and `provr-<PROVR_E2E_PROJECT>c-1` hosts) to
  168. begin clean, so `PROVR_E2E_PROJECT` must not name a real provr project.
  169. If the run is interrupted (Ctrl-C, or `go test -timeout` panicking), cleanup
  170. is skipped and up to three VMs and their tailnet devices stay behind. Remove
  171. them by hand:
  172. ```sh
  173. gcloud compute instances list --project=$PROVR_E2E_GCP_PROJECT \
  174. --filter='labels.provr=managed AND labels.provr-project~^<PROVR_E2E_PROJECT>'
  175. gcloud compute instances delete provr-<project>-1 provr-<project>q-1 provr-<project>c-1 \
  176. --zone=$PROVR_E2E_ZONE --project=$PROVR_E2E_GCP_PROJECT
  177. ```
  178. Then remove the matching devices (`provr-<project>-1`, ...) in the Tailscale
  179. admin console. Instances that do not exist can be left out of the delete
  180. command.
  181. ## Roadmap
  182. **MVP**
  183. - [x] Foundation: CLI skeleton, `provr.yaml` config, core interfaces, CI quality gates (EPIC-001)
  184. - [x] `provr init` (SPEC-005)
  185. - [ ] `provr doctor` (SPEC-006)
  186. - [ ] Remote preview stack on GCE + Tailscale: `up` / `exec` / `logs` / `ls` / `down` (EPIC-003)
  187. - [ ] Cleanup and cost safety: TTL reaper, idle stop, `provr gc` (EPIC-004)
  188. - [ ] MCP server and Claude plugin (EPIC-005)
  189. **Later:** Codex integration, preview URLs on PRs, Secret Manager, public
  190. share links, multi-repo projects, other hosts and exposers (DevPod, local
  191. Docker, Cloudflare Tunnel), and warm pools.
  192. The details are in [anton/roadmap/roadmap.md](anton/roadmap/roadmap.md).
  193. ## Contributing
  194. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. provr
  195. uses spec-driven development with [anton](anton/README.md): every change
  196. starts as a spec in `anton/specs/`. Report security vulnerabilities privately
  197. as described in [SECURITY.md](SECURITY.md), not in public issues.
  198. ## Prior art
  199. provr borrows ideas from
  200. [devcontainer-mcp](https://github.com/aniongithub/devcontainer-mcp),
  201. [PullPreview](https://github.com/pullpreview/action), DevPod and
  202. [Sarthi](https://github.com/tushar5526/sarthi). The comparison is in the
  203. [architecture overview](anton/architecture/overview.md).
  204. ## License
  205. provr is licensed under the Apache License 2.0. See [LICENSE](LICENSE) and
  206. [NOTICE](NOTICE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.