# Deploy keys

When you can't log in or use the CLI interactively to specify a project or deployment, for example in a production build environment, the environment variable `CONVEX_DEPLOY_KEY` can be set to a deploy key to make convex CLI commands run non-interactively.

Deploy keys identify a deployment, project, or team; confer permission to take certain actions with those resources; and can change the behavior of the convex CLI.

### Developing locally does not require a deploy key[​](#developing-locally-does-not-require-a-deploy-key "Direct link to Developing locally does not require a deploy key")

Running `npx convex dev` on a new machine offers the choice to log in or run Convex locally without an account.

Logging in stores a *user token* at `~/.convex/config.json` which is used automatically for all CLI use going forward on that machine. This token grants permission to push code to and read/write data from any deployment this user has access to.

Using Convex locally without logging in ([anonymous development](/cli/local-deployments.md#anonymous-development)) creates a deployment locally and records this preference for this project in the `.env.local` file in the project directory. The *admin key* for this anonymous backend is stored in `~/.convex/anonymous-convex-backend-state/` along with its serialized data.

In either of these cases, there's no reason to set `CONVEX_DEPLOY_KEY`.

### How to set a deploy key[​](#how-to-set-a-deploy-key "Direct link to How to set a deploy key")

Generally deploys keys are set in a dashboard of the service that needs the key but in most shells you can set it right before the command, like

```
CONVEX_DEPLOY_KEY='key goes here' npx convex dev
```

or export it before you run the command

```
export CONVEX_DEPLOY_KEY='key goes here'

npx convex dev
```

or add it to your `.env.local` file where it will be found by `npx convex` when run in that directory.

# Common uses of deploy keys

### Deploying from build pipelines[​](#deploying-from-build-pipelines "Direct link to Deploying from build pipelines")

A *production deploy key* specifies the production deployment of a project and grants permissions to deploy code to it.

> `prod:qualified-jaguar-123|eyJ2...0=`

You can deploying code from a build pipeline where you can't log in (e.g. Vercel, Netlify, Cloudflare build pipelines)

Read more about [deploying to production](https://docs.convex.dev/production/hosting/).

### Deploying to preview deployments[​](#deploying-to-preview-deployments "Direct link to Deploying to preview deployments")

A *preview deploy key* looks like this:

> `preview:team-slug:project-slug|eyJ2...0=`

Use a preview deploy key to change the behavior of a normal `npx convex deploy` command to deploy to a preview branch.

Read more about [preview deployments](/production/multiple-deployments.md#preview).

### Admin keys[​](#admin-keys "Direct link to Admin keys")

An admin key provides complete control over a deployment.

An admin key might look like

> `bold-hyena-681|01c2...c09c`

Unlike other types of deploy key, an admin key does not require a network connection to <https://convex.dev> to be used since it's a irrevocable secret baked into the deployment when created.

These keys are used to control [anonymous](/cli/local-deployments.md#anonymous-development) Convex deployments locally without logging in, but rarely need to be set explicitly.

Setting `CONVEX_DEPLOY_KEY` to one will cause the Convex CLI to run against that deployment instead of offering a choice.

## Rarer types of deploy keys[​](#rarer-types-of-deploy-keys "Direct link to Rarer types of deploy keys")

### Project tokens[​](#project-tokens "Direct link to Project tokens")

A *project token* grants total control over a project to a convex CLI and carries with it the permission to create and use development and production deployments in that project.

> `project:team-slug:project-slug|eyJ2...0=`

Project tokens are obtained when a user grants an permission to use a project to an organization via an Convex OAuth application. Actions made with the token are on behalf of the user so if a user loses access to a project the token no longer grant access to it.

### Development deploy keys[​](#development-deploy-keys "Direct link to Development deploy keys")

A *dev deploy key* might be used to provide an agent full access to a single deployment for development.

> `dev:joyful-jaguar-123|eyJ2...0=`

This can help limit the blast radius when developing with an agent.

To give an agent exclusive access to its own dev deployment, see [Agent Mode](/cli/agent-mode.md).