provr
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
Markdown
[](/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
- {
- "name": "provr",
- "owner": {
- "name": "divait",
- "url": "https://github.com/divait"
- },
- "description": "Marketplace for the provr Claude Code plugin: start and manage provr preview environments.",
- "plugins": [
- {
- "name": "provr",
- "source": "./integrations/claude",
- "description": "Start and manage provr preview environments from Claude Code."
- }
- ]
- }
README.md · README · 263 lines
- # provr
- **Isolated, full-stack preview environments for coding agents, on your own GCP project.**
- provr lets an agent (Claude Code, Codex, or any MCP client) or a human run the
- current git worktree as a complete Docker Compose stack on a remote host. It
- returns a private URL, runs tests against the stack, and tears it down
- afterwards. Every preview expires on its own.
- > **Status: pre-alpha.** `provr init` (GCP project and Tailscale setup),
- > `provr.yaml` loading, `doctor`, and the preview commands (`up`, `exec`,
- > `logs`, `ls`, `down`), `gc`, and the MCP server (`provr mcp`) work. The MVP is being built now; see [Roadmap](#roadmap).
- ## Why
- When several agents work in parallel git worktrees on one dev server, they
- compete for ports, CPU and RAM as soon as they try to run what they built. So
- they either skip testing or test in a messy shared environment.
- provr moves each preview to a warm host in GCP:
- - **Isolated:** every worktree gets its own compose project, network and
- volumes. No port clashes, even when the compose file hard-codes ports and
- container names.
- - **Built from what's actually in the worktree:** uncommitted changes
- included, so agents can test before they commit or open a PR.
- - **Private:** hosts have no public IP. Each preview gets its own hostname on
- your Tailscale tailnet, which you can open from a laptop or phone.
- - **Cleaned up by design:** previews have a TTL (maximum 12 h), idle hosts stop
- themselves, and unused hosts are deleted. Cleanup doesn't depend on the agent
- that created them.
- - **Works with any agent:** a single Go binary that contains both the CLI and
- an MCP server.
- ## How it works
- ```
- Dev server (agents in git worktrees) Project's own GCP project
- ┌───────────────────────────────────┐ ┌─────────────────────────────────────┐
- │ agent ─▶ provr (MCP / CLI) │ Tailscale │ preview host (GCE VM, warm Docker) │
- │ up · exec · logs · down │ ── SSH ──▶ │ ├─ preview pr-42 (compose + sidecar)┼─▶ pr-42.<tailnet>.ts.net
- │ │ + rsync │ └─ preview pr-43 (compose + sidecar)┼─▶ pr-43.<tailnet>.ts.net
- └───────────────────────────────────┘ └─────────────────────────────────────┘
- your phone / laptop ── tailnet ──▶ preview URLs
- ```
- 1. `provr up` finds or starts the project's host (or creates one).
- 2. It copies the worktree with rsync, then places your gitignored secrets on
- top of it from a local `secrets_dir`.
- 3. It generates a compose **override** that resets host ports and
- `container_name`s and adds a Tailscale sidecar. Your compose files are
- never edited.
- 4. It runs `docker compose up --build`, waits for the healthcheck, and returns
- the URLs and the expiry time.
- ## Usage
- ```bash
- provr init --gcp-project my-previews --zone us-central1-a # one-time project setup (works now)
- provr doctor # check the repo's compose setup
- provr up # preview the current worktree
- provr exec <id> --script test # run the project's tests in it
- provr logs <id> api
- provr ls
- provr down <id>
- ```
- Agents use the same operations as MCP tools through `provr mcp`
- (`preview_up`, `preview_exec`, `preview_logs`, `preview_status`,
- `preview_list`, `preview_down`).
- ### `provr.yaml`
- ```yaml
- version: 1
- project: myapp
- gcp:
- project: myapp-previews
- zone: us-central1-a
- host:
- machine_type: e2-standard-4
- max_previews: 2
- compose:
- files: [docker-compose.yml]
- secrets_dir: ~/.provr/myapp # mirrors repo paths, e.g. configs/env/api.env
- expose:
- web: 3000
- api: 8000
- healthcheck:
- service: api
- path: /health
- commands:
- test: "docker compose exec -T api pytest"
- ttl:
- default: 4h
- max: 12h
- agents:
- auto_preview: on_change # or on_request
- ```
- A commented example with every field is in
- [examples/provr.yaml](examples/provr.yaml); the schema is in
- [SPEC-002](anton/specs/SPEC-002-project-config/spec.md).
- ## Install
- With Go (1.25 or newer):
- ```bash
- 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`.
- ## Install for Claude Code
- 1. Install the binary (see [Install](#install)) and make sure it is on
- `PATH`.
- 2. Add the plugin inside Claude Code:
- ```
- /plugin marketplace add divait/provr
- /plugin install provr@provr
- ```
- 3. Export `TS_OAUTH_CLIENT_ID` and `TS_OAUTH_CLIENT_SECRET` in the shell that
- starts `claude` (for example in herdr's environment). The plugin never
- stores them. Be logged in with `gcloud`; after a re-login, reconnect the
- MCP server with `/mcp`.
- The plugin runs `provr mcp` and adds a preview skill: when a task changes
- code, the agent starts a preview, runs the tests in it, and reports the URLs.
- Control this with `agents.auto_preview` in `provr.yaml`:
- - `on_change` (recommended, default): start a preview when a task changes code.
- - `on_request`: start a preview only when you ask.
- See [examples/provr.yaml](examples/provr.yaml).
- Release rule: bump `version` in
- `integrations/claude/.claude-plugin/plugin.json` together with the release tag
- (`v0.1.0` needs `0.1.0`); CI fails a tagged build that disagrees.
- ## Requirements (MVP)
- - **Dev server:** Linux or macOS with `gcloud`, `git`, `rsync`, Docker with
- Compose ≥ 2.24, and Tailscale.
- - **Per project:** a dedicated GCP project with billing enabled, and a
- Tailscale OAuth client (`TS_OAUTH_CLIENT_ID` / `TS_OAUTH_CLIENT_SECRET`)
- that is allowed to use `tag:provr` and has the `auth_keys` and
- `devices:core` scopes (`policy_file:read` is optional).
- - **Repo:** a working `docker-compose.yml`.
- ## Building from source
- Requires Go 1.25+.
- ```bash
- make build # builds bin/provr with version info
- make check # gofmt, go vet, golangci-lint, tests (-race), file-length limits
- make smoke # builds a binary and checks the CLI behaves as specified
- ```
- Or without make: `go build -o provr ./cmd/provr`.
- ## Live GCE test
- `internal/host/gce/live_test.go` (build tag `e2e`) exercises the GCE host
- provider against real GCP and Tailscale. It is never part of `go test ./...`
- or `make check`. It creates one VM (plus one more if the optional quota or
- concurrency checks are enabled) and deletes it afterwards, so it costs a few
- minutes of VM time.
- Prerequisites:
- - `provr init` has been run on the GCP project, so `provr-operator`,
- `provr-net`/`provr-subnet` and Cloud NAT exist.
- - `gcloud auth login` as a user who can impersonate `provr-operator`.
- - A Tailscale OAuth client with the `auth_keys` and `devices:core` scopes, and
- a tailnet policy that defines `tag:provr`.
- Environment:
- | Variable | Required | Meaning |
- |----------|----------|---------|
- | `PROVR_E2E_GCP_PROJECT` | yes | GCP project id |
- | `PROVR_E2E_ZONE` | yes | zone, e.g. `us-central1-a` |
- | `TS_OAUTH_CLIENT_ID`, `TS_OAUTH_CLIENT_SECRET` | yes | Tailscale OAuth client |
- | `PROVR_E2E_PROJECT` | no | provr project name (default `provr-e2e-tmp`); must not name a real provr project, see below |
- | `PROVR_E2E_MACHINE_TYPE` | no | default `e2-standard-2` |
- | `PROVR_E2E_QUOTA_MACHINE_TYPE` | no | machine type in a zero-quota family, e.g. `c3-standard-4`; enables the quota check |
- | `PROVR_E2E_CONCURRENT` | no | `1` enables the two-parallel-Ensure check |
- Run it (it skips when the required variables are missing):
- ```sh
- make e2e-gce
- # or: go test -tags e2e -run TestLive -count=1 -timeout 30m -v ./internal/host/gce
- ```
- Before it starts, the test deletes `provr-<PROVR_E2E_PROJECT>-1` (and the
- `provr-<PROVR_E2E_PROJECT>q-1` and `provr-<PROVR_E2E_PROJECT>c-1` hosts) to
- begin clean, so `PROVR_E2E_PROJECT` must not name a real provr project.
- If the run is interrupted (Ctrl-C, or `go test -timeout` panicking), cleanup
- is skipped and up to three VMs and their tailnet devices stay behind. Remove
- them by hand:
- ```sh
- gcloud compute instances list --project=$PROVR_E2E_GCP_PROJECT \
- --filter='labels.provr=managed AND labels.provr-project~^<PROVR_E2E_PROJECT>'
- gcloud compute instances delete provr-<project>-1 provr-<project>q-1 provr-<project>c-1 \
- --zone=$PROVR_E2E_ZONE --project=$PROVR_E2E_GCP_PROJECT
- ```
- Then remove the matching devices (`provr-<project>-1`, ...) in the Tailscale
- admin console. Instances that do not exist can be left out of the delete
- command.
- ## Roadmap
- **MVP**
- - [x] Foundation: CLI skeleton, `provr.yaml` config, core interfaces, CI quality gates (EPIC-001)
- - [x] `provr init` (SPEC-005)
- - [ ] `provr doctor` (SPEC-006)
- - [ ] Remote preview stack on GCE + Tailscale: `up` / `exec` / `logs` / `ls` / `down` (EPIC-003)
- - [ ] Cleanup and cost safety: TTL reaper, idle stop, `provr gc` (EPIC-004)
- - [ ] MCP server and Claude plugin (EPIC-005)
- **Later:** Codex integration, preview URLs on PRs, Secret Manager, public
- share links, multi-repo projects, other hosts and exposers (DevPod, local
- Docker, Cloudflare Tunnel), and warm pools.
- The details are in [anton/roadmap/roadmap.md](anton/roadmap/roadmap.md).
- ## Contributing
- Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. provr
- uses spec-driven development with [anton](anton/README.md): every change
- starts as a spec in `anton/specs/`. Report security vulnerabilities privately
- as described in [SECURITY.md](SECURITY.md), not in public issues.
- ## Prior art
- provr borrows ideas from
- [devcontainer-mcp](https://github.com/aniongithub/devcontainer-mcp),
- [PullPreview](https://github.com/pullpreview/action), DevPod and
- [Sarthi](https://github.com/tushar5526/sarthi). The comparison is in the
- [architecture overview](anton/architecture/overview.md).
- ## License
- provr is licensed under the Apache License 2.0. See [LICENSE](LICENSE) and
- [NOTICE](NOTICE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.