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 Claude Code 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
• Claude Code CLI installed as claude

Verify the agent runtime before starting the bridge:

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.

Create a CLI API key

In the web app, open user settings and create an API key for local CLI access. The CLI uses this key to register sessions, claim thread work, and stream assistant output.

Configure a local profile

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

pnpm cli:dev setup

The setup wizard asks for:

• the Convex deployment URL from NEXT_PUBLIC_CONVEX_URL
• the API key you created in the web app
• the project to bind this machine to
• a profile name and local path

The result is a saved profile in ~/.config/convoy/config.toml. 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

Start the long-running local agent process:

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 Claude Code for claimed work.

Send a test thread

1. Open the project in the web app.
2. Start a new AI thread.
3. Select the online Claude Code profile.
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 convoy status, confirm the CLI process is still connected, and verify that claude 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