convex-deploy-guard
get-convex/agent-skills
Classify and announce Convex deployment targets before acting; gate production changes with fresh per-action consent.
What is convex-deploy-guard?
A safety guard that identifies which Convex deployment (dev, preview, or prod) a command will affect, announces it explicitly, and requires fresh consent before any production-affecting action. Use this to prevent accidental deployments to the wrong environment.
- Identifies and classifies the target Convex deployment (local-anonymous, dev, preview, or prod) before executing any command
- Announces the deployment target in one line before any deployment-affecting action
- Requires fresh explicit per-action consent for production deployments within the current session
- Enforces read-only session mode when requested, blocking all mutations for the remainder of the session
- Splits production MCP flags by risk level: read-only audits use --cautiously-allow-production-pii; mutations require --dangerously-enable-production-deployments
How to install convex-deploy-guard
npx skills add https://github.com/get-convex/agent-skills --skill convex-deploy-guard- Convex project with .env.local or convex.json configured
- Access to the official Convex MCP status tool (or ability to call npx convex env list)
- Understanding of your project's deployment structure (which are dev, preview, prod)
How to use convex-deploy-guard
- 1.Before running any deployment-affecting command, identify the target: check CONVEX_DEPLOYMENT in .env.local, convex.json, and whether CONVEX_DEPLOY_KEY is set; or call the Convex MCP status tool
- 2.Announce the target in one line (e.g., 'target: dev (joyful-capybara-123, personal dev)') before executing the command
- 3.For production deployments, state exactly what will change and get an explicit yes in the current session — earlier consent or consent for a different target does not carry
- 4.When starting the MCP, default to a non-prod deployment; use --cautiously-allow-production-pii only for read-only production audits, and --dangerously-enable-production-deployments only when the user explicitly requests production mutations
- 5.If a deployment appeared to have no effect, re-run the identification step (step 1) rather than re-deploying — the change likely landed on a different deployment
- 6.If you cannot determine the target deployment, use the status tool or compare npx convex env list fingerprints — never guess
Use cases
- Prevent accidental deployments to production by confirming the target environment before running npx convex deploy
- Audit production data and logs safely using read-only mode without risking mutations
- Diagnose why a deployment had no visible effect by re-identifying the actual target deployment
- Enforce team discipline: identify, announce, then act — separating discovery from execution
- Lock the session into read-only mode when exploring or investigating without permission to make changes
- Convex developers managing multiple deployments (dev, preview, prod) on one machine
- Teams requiring explicit approval gates for production changes
- Anyone using the Convex MCP (Model Context Protocol) server for agent-assisted deployments
- DevOps and platform engineers enforcing deployment safety policies
convex-deploy-guard FAQ
--cautiously-allow-production-pii enables read-only tools for auditing production data and logs without risk of mutation. --dangerously-enable-production-deployments enables mutating tools like deploy, env set, and run. They are separate risk levels and should not both be enabled by default; use only the one the user explicitly requested.
No. Production consent is per-action, per-target, and per-session. You must state exactly what will change on which deployment and get a fresh explicit yes each time, even within the same session.
Do not re-deploy harder. Instead, re-run the identification step (step 1) to determine which deployment actually received the change. The command almost certainly landed on a different deployment than the one being observed.
When the user says 'read-only' or 'don't change anything', start the MCP with --disable-tools run,envSet,envRemove and honor that mode absolutely for the rest of the session — no deploys, env changes, mutations via run, or imports.
Stop and find out. Use the Convex status tool or compare npx convex env list fingerprints across environments. Never guess which deployment will be affected.
Full instructions (SKILL.md)
Source of truth, from get-convex/agent-skills.
name: convex-deploy-guard description: "Classify + announce the target Convex deployment before any deployment-affecting command; fresh explicit consent for prod actions; session read-only mode."
<!-- GENERATED from convex-agents content/capabilities/deploy-guard.json — do not edit by hand. -->Deployment target guard
Deployments are not interchangeable, and most incidents start with a command aimed at the wrong one. Every Convex project has several (personal dev, preview, prod — often across multiple projects on one machine). This guard is the standing discipline: identify, announce, then act — and treat prod as consent-gated, per action, per session.
Workflow
- IDENTIFY before you act: read
CONVEX_DEPLOYMENTin .env.local,convex.json, and whetherCONVEX_DEPLOY_KEYis set; or call the official Convex MCPstatustool. Classify the target: local-anonymous | dev | preview | prod. If two sources disagree, resolve before proceeding. - ANNOUNCE in one line before any deployment-affecting command:
target: dev (joyful-capybara-123, personal dev). Never run the command in the same breath as discovering the target — announce first. - PROD needs a FRESH explicit yes: before
npx convex deploy(when it resolves to prod),npx convex run --prod,env seton prod, snapshotimport/exporton prod, or starting the MCP with prod access — state exactly what will change on which deployment and get an explicit yes in THIS session. A yes given earlier, or for a different target, does not carry. - MCP safety defaults: start the official MCP scoped non-prod (
--deployment dev). The two prod flags are DIFFERENT risk levels — keep them split: a read-only prod audit (advisor/insights reading data/logs/insights) passes ONLY--cautiously-allow-production-pii(read tools);--dangerously-enable-production-deployments(which enables MUTATING prod tools) stays OFF unless the user explicitly asked to CHANGE prod this session. Never pair them by default — 'look at prod' must not silently grant 'mutate prod'. - READ-ONLY session mode: when the user says 'read-only' / 'don't change anything', honor it absolutely for the rest of the session — no deploy, no env set/remove, no mutations via
run, no imports; start the MCP with--disable-tools run,envSet,envRemove. - Wrong-deployment diagnosis: when a deploy 'didn't change anything', do NOT re-deploy harder. Re-run step 1 — the deploy almost certainly landed on a different deployment than the one being observed.
- Ambiguity = stop: if you cannot determine which deployment a command will hit, find out (status tool; compare
npx convex env listfingerprints) — never guess.
Rules
- Classify and announce the target BEFORE every deployment-affecting command — identification and action are two separate steps.
- Prod consent is per-action, per-target, per-session: state what changes where, get a fresh explicit yes.
- Keep the two prod MCP flags split by risk: --cautiously-allow-production-pii (read-only) for an audit; --dangerously-enable-production-deployments (mutating) only when the user explicitly asks to change prod. Both are user-spoken-only; default every MCP start to a non-prod deployment selector.
- Read-only mode, once requested, is absolute for the session — including 'harmless' mutations.
- A deploy that seemed to do nothing means the WRONG deployment changed — diagnose the target, don't re-run.
- This guard composes: ship, env, migrate, and seed run it as their step 0; it is not itself a deploy tool.
Related skills
More from get-convex/agent-skills and the wider catalog.
convex-design
Design and build reactive, type-safe production backends on Convex with schema, auth, real-time, and LLM workflows.
convex-docs
Fetch version-current Convex docs instead of writing stale APIs from memory.
convex-domains
Point your own domain at a Convex app with DNS records, custom-domain attachment, and auth-origin rebinding.
convex-env
Set and manage Convex deployment environment variables and secrets securely.
convex-expert
Convex backend specialist for queries, mutations, actions, schemas, and real-time functions.
convex-explain-app
Analyze your Convex app's data model, functions, auth, and request flows without modifying it.