Quickstart: run from source

This guide is for contributors who want the full Convoy stack running from a local checkout: Convex backend, Next.js web app, and the CLI bridge executing your selected runtime against the same dev deployment.

If you instead have access to an existing deployment and just want the CLI wired up, see Quickstart: join a deployment.

Prerequisites

• Node.js 18+
• pnpm
• a Convex dev deployment (free tier is fine)
• Clerk keys for local authentication
• An installed, authenticated supported runtime

Verify the runtime before starting the bridge. For Claude Code:

claude --version

Install dependencies

From the repository root:

pnpm install
cp apps/web/.env.example apps/web/.env.local

Fill apps/web/.env.local with your Convex and Clerk values. At minimum, the web app needs NEXT_PUBLIC_CONVEX_URL, NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, and CLERK_SECRET_KEY. See Environment variables for the full matrix.

Start Convex

In one terminal:

pnpm web:convex:dev

Keep this process running. It syncs Convex schema and functions from apps/web/convex, tails backend logs, and provides the deployment URL used by the web app and CLI profile.

Start the web app

In a second terminal:

pnpm web:dev

Open https://app.convoy.localhost. Sign in, create or join an organization, and create a project. The project is the unit that CLI profiles and AI threads target.

Configure a local profile

In a third terminal, from the repository or worktree you want the runtime to operate on:

pnpm cli:dev login

The setup wizard asks for:

• the Convex deployment URL from NEXT_PUBLIC_CONVEX_URL
• browser approval in the local web app, which issues the API key automatically
• the project to bind this machine to
• a profile name and local path

The wizard saves a profile in ~/.config/convoy/config.toml and starts the connection. Leave that terminal running. For unattended setup, see API keys for scripts and headless machines. The CLI resolves a profile by --profile, CONVOY_PROFILE, matching the current working directory against saved paths, then the default profile. See Config file (config.toml) for the full schema and resolution rules.

Connect the CLI bridge

Browser login starts the bridge. After stopping it, reconnect with:

pnpm cli:dev connect

For more logging while developing:

CONVOY_CLI_DEBUG=1 pnpm cli:dev connect

When connected, the CLI registers a session with Convex, heartbeats in the background, watches for pending threads in the configured project, and runs the selected runtime for claimed work.

Send a test thread

1. Open the project in the web app.
2. Start a new AI thread.
3. Select your online profile, working path, and runtime.
4. Send a small prompt, such as asking it to inspect the repository structure.
5. Watch the streamed assistant response appear in the web UI.

If nothing runs, check pnpm cli:dev status, confirm the CLI process is still connected, and verify that your runtime executable is available on the same PATH used by the terminal running pnpm cli:dev connect.

Next steps

• Read How Convoy works for the runtime model
• Read Profiles, paths, and status
• Read CLI architecture and lifecycle
• Read the Contributing overview for the repository map