Connect Convex

Connect your Convex team so the Convex CLI on this project's Template box and devboxes can use it without a separate sign-in on every box. Access follows your permissions in Convex.

Connect your team

1. In the desktop app, open Integrations → Convex and choose Connect Convex.
2. Choose Open Convex, check that the one-time code matches, and select Confirm. Convex will describe the request as Convex CLI.
3. Return to boxes.dev, select your Convex team, and choose Connect team.

This sign-in will grant boxes.dev access to your Convex account. Your personal access token will stay encrypted in boxes.dev; your boxes will receive only expiring credentials for the team you choose. Each boxes.dev project has its own connection. Restricted access to one Convex project or deployment is not available yet.

Use the Convex CLI

Run boxes-convex from your project using the same arguments you would pass to npx convex. For example, run boxes-convex dev to watch and push your Convex functions, or boxes-convex run example:status to call a function.

The launcher uses your project's installed Convex version and its existing deployment selection. Install the convex package in your project first. If boxes-convex is unavailable, update the box's software in boxes.dev.

On a fresh checkout, select an existing deployment first with boxes-convex deployment select <deployment-name>, then run boxes-convex dev. Find the deployment name in your Convex dashboard. Your token will still cover the selected Convex team.

Convex CLI's personal account check currently rejects team tokens. The launcher skips that check only for the expiring team credential delivered by boxes.dev. Convex still checks your token and deployment permissions. A direct npx convex dev command can hit this error; use boxes-convex dev with this integration. Other CLI commands can read the same native login file. The CLI's interactive account/team discovery also requires a personal token; select the deployment explicitly when setting up a checkout.

The credentials expire after eight hours and renew automatically. Terminals, Codex, and Claude will use the replacement on their next command. For an ordinary boxes-convex dev watcher, the launcher will briefly restart Convex when renewed credentials arrive, keeping the same arguments and terminal.

Automatic restarts don't apply to commands using your own credentials, or to --once, --until-success, --configure, --run, --run-sh, or --start. This keeps one-time work and startup hooks from running again during renewal. If one of those commands reports an authentication error, run it again to use the renewed credential.

If you already signed in to Convex on a box, boxes.dev will preserve that login. A key set by your project or command can also take precedence over the managed login. Check those credentials if a command uses a different account or has different permissions than you expect.

Reconnect or remove access

If the page shows Convex needs you to sign in again, choose Reconnect and finish the sign-in and team selection. To choose another team, open the page's options menu and choose Change team.

To stop using the integration, choose Remove connection in the options menu and confirm. boxes.dev will revoke the saved sign-in and current team token, remove the managed login from running boxes, and stop renewing access. Sleeping boxes will remove it after waking. Previously issued credentials may remain valid until they expire. Personal logins will be left alone.

Running convex logout only removes the login file on that box. While the integration is connected, boxes.dev will restore the managed token. Remove the connection in Integrations to stop using it.

Your team's Convex permissions still control production access. This integration doesn't grant a separate production role, and your organization's sign-in policy may require you to authenticate through its identity provider again.