Working with Multiple Deployments

By default, each project has a single shared prod deployment and each developer working on the project has their own dev deployment.

For more advanced use cases, you may want to create more cloud deployments. For instance:

• Create a preview deployment for every feature branch you push.
• Give an isolated dev deployment to every coding agent.
• Shard your production workload across multiple deployments.
• Add a staging environment for your project.

Creating more deployments

Using preview deployments

Preview deployments are a simple way to automatically create a temporary deployment for each feature branch you create. These deployments are automatically cleaned up 5 days after they are created (14 days on the Professional, Business and Enterprise plans).

Convex preview deployments are in beta

Convex preview deployments are currently a beta feature. If you have feedback or feature requests, let us know on Discord!

Setting up preview deployments

Preview deployments can be automatically created using the npx convex deploy command. You will need to set the CONVEX_DEPLOY_KEY environment variable to a preview deploy key. You can generate a preview deploy key in the dashboard from the settings page of the project.

To deploy code to a preview deployment, use:

npx convex deploy --preview-create="my-preview-deployment-name"

This command will create a preview deployment if needed. If a preview deployment with the same name already exists, the existing preview deployment and its data will be deleted, and a new one will be created.

If you’re deploying your code from Vercel, Netlify, Cloudflare Pages, or GitHub Actions, you can simply use npx convex deploy. The preview name will automatically be determined. With that workflow, you can reuse the same deploy command for preview deployments and production deployments: for preview deployments, set the CONVEX_DEPLOY_KEY environment variable to a preview deploy key, and in production, set it to your production environment’s deploy key.

Seeding initial data

If you want to automatically create sample data when a preview deployment is created, you can use --preview-run:

npx convex deploy --preview-create="my-preview-deployment-name" --preview-run=<functionName>

Replace <functionName> by the name of a Convex function that will be ran if a preview deployment is created. --preview-run is ignored npx convex deploy doesn’t create a preview deployment.

Note that if the function call fails, the deploy command will fail, but the new preview deployment will have already been provisioned. Best course of action is to fix the issue in the function and redeploy.

From the command line

Interactively

To create a new deployment manually, run the following command in your project:

npx convex deployment create

This command will allow you to interactively choose the deployment type, region, and reference for the new deployment.

Convex version requirement

To use npx convex deployment create, you must use the convex NPM package version 1.34.0 or later.

From a script (e.g. agent setup script)

You can also use npx convex deployment create in scripts to automatically manage deployments:

npx convex deployment create <reference> --type=<type> [options] [--select]
# For instance:
# npx convex deployment create dev/james/feature-payment-integration --type=dev --region us --expiration "in 7 days" --select

When including --select, the deployment you created will be used by the npx convex commands you run after.

The reference is a string that uniquely identifies the deployment within a project. It must be 3 to 100 characters and contain only alphanumeric characters, dashes, and slashes. The reference is used by the Convex dashboard and by npx convex to identify the deployment, so we recommend using descriptive names.

Below are some examples of how to use npx convex deployment create with popular tools:

Using the Codex app

Open the Codex app settings and go to Environments. Select the environment for your project or create one if needed. Use the following setup script:

npm ci && npx convex deployment create --type=dev my-team:my-project:dev/$USER-codex/$(basename \"$(dirname \"$CODEX_WORKTREE_PATH\")\") --select"

Replace my-team and my-project with your team and project slugs.

When starting a new worktree, select the environment that you just created.

Using Conductor

Add the following setup command to the conductor.json file of your project:

{
  "scripts": {
    "setup": "npm ci && npx convex deployment create --type=dev my-team:my-project:dev/$USER-conductor/$CONDUCTOR_WORKSPACE_NAME --select"
  }
}

Replace my-team and my-project with your team and project slugs.

Using Cursor local worktrees

Add the following setup command to the .cursor/worktrees.json file of your project:

{
  "setup-worktree": [
    "npm ci",
    "npx convex deployment create --type=dev my-team:my-project:dev/$USER-cursor/$(basename \"$PWD\") --select"
  ]
}

Replace my-team and my-project with your team and project slugs.

Using T3 Code

Click on Add action in the top bar. Enable Run automatically on worktree creation and use the following command:

npm ci && npx convex deployment create --type=dev my-team:my-project:dev/$USER-t3code/$(basename "$PWD" | sed 's/^t3code-//') --select

Replace my-team and my-project with your team and project slugs.

Through the API

You can also create deployments through the management API.

Targeting different deployments

If you’re manually managing multiple dev deployments, you can use npx convex deployment select to change the deployment used by npx convex dev and other commands:

# To select a deployment in the same project:
npx convex deployment select dev/james/feature-payment-integration

# To select a deployment in another project:
npx convex deployment select my-project:dev/james/feature-payment-integration

# To select a deployment in another team:
npx convex deployment select my-team:my-project:dev/james/feature-payment-integration

If you only need to run a single command on another deployment, you can use --deployment:

npx convex env list --deployment dev/james/feature-payment-integration

Convex version requirement

To use npx convex deployment select and --deployment, you must use the convex NPM package version 1.34.0 or later.

Deployment types

There are three types of cloud deployments in Convex:

Default settings

Type
Reference	dev/[creator]	preview/[branch]	production
Expiration	—	5 days (Free and Starter plans) 14 days (Professional, Business, and Enterprise plans)	—
Dashboard permissions	Can be edited by every team member		Can only be edited by project or team admins
Server logs in clients	Server logs are sent to the client		Server logs are not sent to the client
Server errors	Details of server errors are sent to the client		Details of server errors are not sent to the client (unless the error is wrapped in ConvexError)
Dashboard edit confirmation	No protection against accidental edits		Asks for confirmation before editing

Customize settings

The table above shows the default settings for deployments in a type. You can modify the settings of an individual deployment from the deployment’s settings page in the dashboard.

Limits

Every deployment you create counts towards the deployment limit of your team.

You can set an expiration date when creating a deployment with --expiration. Run npx convex deployment create --help to learn more.

You can change the expiration time for an existing deployment in the dashboard deployment settings.