convex-env
get-convex/agent-skills
Set and manage Convex deployment environment variables and secrets securely.
What is convex-env?
This skill manages sensitive configuration for Convex deployments using the Convex CLI. Use it to store API keys, credentials, and other secrets as deployment environment variables that can be safely read in actions without committing them to version control.
- Set environment variables per Convex deployment with `npx convex env set`
- Read secrets via process.env inside actions (not queries/mutations)
- List all configured environment variables with `npx convex env list`
- Isolate secrets from code and version control
- Support different values across multiple deployments
How to install convex-env
npx skills add https://github.com/get-convex/agent-skills --skill convex-env- Convex CLI installed (npx convex)
- Access to Convex deployment configuration
How to use convex-env
- 1.Run `npx convex env set KEY value` to store each secret for the current deployment
- 2.Access the secret in your action code using `process.env.KEY`
- 3.For local development, add secrets to .env.local (never commit this file)
- 4.Run `npx convex env list` to verify all environment variables are set correctly
- 5.Repeat the env set command for each deployment (staging, production, etc.) with appropriate values
Use cases
- Storing API keys for third-party services in production deployments
- Managing database credentials and connection strings
- Configuring authentication tokens for external APIs
- Keeping local development secrets in .env.local without committing them
- Rotating secrets across staging and production environments
- Backend developers building Convex applications
- DevOps engineers managing deployment configurations
- Teams handling sensitive credentials and API keys
convex-env FAQ
No. process.env only works in actions (functions marked with 'use node'). Queries and mutations run in the Convex cloud and cannot access Node.js environment variables.
Run `npx convex env set` separately for each deployment. The Convex CLI will prompt you to select the deployment, and each one maintains its own set of environment variables.
Create a .env.local file in your project root with your local secrets, then add .env.local to .gitignore. The Convex CLI will read from this file during local development.
Yes. Convex stores deployment environment variables securely and they are only accessible to your actions at runtime.
Yes. Environment variables take effect immediately after you run `npx convex env set`. No redeploy is required.
Full instructions (SKILL.md)
Source of truth, from get-convex/agent-skills.
name: convex-env description: "Set and wire Convex deployment env vars / secrets for the app."
<!-- GENERATED from convex-agents content/capabilities/env.json — do not edit by hand. -->Manage env vars + secrets
Store secrets as Convex deployment env vars (npx convex env set), read them with process.env in actions, never commit them.
Workflow
npx convex env set KEY value(per deployment).- Read via process.env.KEY inside actions (not queries/mutations).
- Never hardcode or commit secrets; add to .env.local only for local.
- Confirm with
npx convex env list.
Rules
- Secrets live in Convex env vars, never in code or git.
- process.env only in actions ('use node' if needed), not queries/mutations.
- Different deployments need their own values.
Related skills
More from get-convex/agent-skills and the wider catalog.
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.
convex-improve-convex-plugin
Send your coding session to Convex for AI-powered system improvements and quickstart refinement.
convex-insights
Query Convex app logs and health in natural language with evidence-backed answers and dashboard links.
convex-launch-readiness
Unified backend readiness score with prioritized fix plan—run all Convex audits, dedupe findings, and dispatch fixes.
convex-migrate
Safely migrate schema and backfill data on live Convex apps without downtime.