Docs

Quickstart: join a deployment

Install the Convoy CLI, connect it to an existing deployment, and send your first AI thread.

This guide is for teammates joining an existing Convoy deployment. You will install the CLI, generate an API key, and start the long-running agent so threads sent from the web UI can execute Claude Code on your machine.

If your team does not have a deployment yet, start with Deploy Convoy. If you want to run everything from a monorepo checkout, see Quickstart: run from source.

Prerequisites

  • a Convoy account on the target deployment
  • membership in at least one project on that deployment
  • Claude Code CLI installed as claude (the current supported runtime)
  • Node.js 18+

Verify the agent runtime is available:

claude --version

1. Create an API key

Open the Convoy web app, go to user settings, and create a CLI API key. The key acts on behalf of your user — it inherits your project access and nothing more. See API keys.

Keep the key handy; the setup wizard will ask for it next.

2. Install the CLI

npm install -g @useconvoy/cli
convoy --help

3. Run the setup wizard

From the repository or directory you want Claude Code to operate on:

convoy setup

The wizard asks for:

  • the deployment URL (your admin can share this — it looks like https://your-deployment.convex.cloud)
  • the API key you just created
  • the project this machine should bind to
  • a profile name

The result is a saved profile in ~/.config/convoy/config.toml. See Config file (config.toml) for the full schema.

4. Start the bridge

convoy connect

This is a long-running process. It registers a CLI session, heartbeats, watches for pending threads in the selected project, and runs Claude Code for claimed work.

5. Send a test thread

  1. Open a project you have access to in the web app.
  2. Start a new AI thread.
  3. Select your online profile.
  4. Send a small prompt.
  5. Watch the streamed assistant response appear inline.

If nothing runs, check convoy status, confirm convoy connect is still attached, and verify claude is on the same PATH as the terminal running the bridge. CLI troubleshooting has the longer symptom list.

Next steps

How Convoy works

The product model, the runtime model, and how a thread travels from the web app to your machine.

Quickstart: run from source

Clone the repo, start Convex + Next.js, and point the CLI at your local dev deployment.

On this page

Prerequisites1. Create an API key2. Install the CLI3. Run the setup wizard4. Start the bridge5. Send a test threadNext steps