Setup and connect

convoy setup creates a saved profile.

convoy connect starts the long-running process that claims queued threads and streams agent output back to Convoy.

Interactive setup

convoy setup

The setup wizard guides you through:

Convex URL
authentication — Log in with browser (recommended; approve in the web app and a fresh API key is issued automatically) or paste an API key manually
project selection
profile naming
workspace folder

convoy login runs the same wizard with browser login pre-selected:

convoy login

The CLI prints an approve link and opens your browser. On headless machines or devcontainers, use the printed backup code instead: open /device in the web app on any signed-in browser and enter the code.

Non-interactive setup

convoy setup \
  --url https://your-deployment.convex.cloud \
  --api-key sk_user_xxx \
  --project proj_abc123 \
  --profile-key work \
  --profile "Work" \
  --path .

Use this mode for scripts, bootstrap steps, or repeatable machine setup. --path . saves the directory where the command is run. Relative paths are resolved before writing the profile. Add --force to overwrite an existing profile key.

Connect

convoy connect

Flag	Default	Purpose
`--profile <key>`	resolved from cwd / env / default	Which saved profile to use
`--name <name>`	current folder name	Display name for this session in the web app
`--repo <path>`	current directory	Path to the repository the agent runs in
`-c, --concurrency <n>`	profile value, otherwise `5` (max `50`)	How many claimed threads this session processes in parallel
`--buffered`	off (streaming on)	Send whole agent events only, instead of streaming partial (delta) events token-by-token in the web app
`--isolated`	off	Run agents in an OS-level sandbox restricted to the profile's paths (details)
`--codex-exec`	off (app-server on)	Run Codex threads through non-interactive `codex exec --json` instead of the `codex app-server` protocol
`--provider-key <name>`	profile assignment	Use a stored Bedrock or Mantle key for this run without changing the profile (details)
`-s, --stream <path>`	—	Replay a JSONL fixture instead of running a real runtime
`-d, --delay <ms>`	`1500`	Delay between replayed lines when using `--stream`

Streaming applies for the lifetime of the connection and is on by default. Turn it off with --buffered, or per profile with streaming = false in config.toml; the flag wins when both are set.

Concurrency resolves the same way: an explicit --concurrency value wins, otherwise the profile's concurrency value is used, then the default 5. The profile value must be an integer from 1 through 50.

--isolated works the same way (isolated = true in config.toml, flag wins). It sandboxes every spawned agent to the profile's folders using the OS's native mechanism — supported for Claude Code and Codex; Cursor and OpenCode runs fail with a clear error rather than running unsandboxed. See isolation options.

The Codex transport is also connection-level, and the app-server transport is the default. It unlocks the interactive Codex features in the web app: mid-run approval prompts and questions ("Ask to approve" mode), read-only Plan mode, steering queued messages into a running turn, live deltas, and the context-window meter. Pass --codex-exec to run Codex through non-interactive codex exec instead, where those modes degrade to sandboxed never-asks behavior. The app-server transport requires codex-cli ≥ 0.142; an older binary is detected at connect time and downgraded to codex exec with a warning.

When connected, the CLI registers a session, heartbeats in the background, watches for pending threads in the profile's project, and runs the selected runtime for claimed work. It only processes threads the profile's user can access.

Debugging and simulation

Use debug logging when you want to inspect runtime behavior:

CONVOY_CLI_DEBUG=1 convoy connect   # Debug logs, truncated at 400 chars
CONVOY_CLI_DEBUG=2 convoy connect   # Debug logs, full JSON output (no truncation)

Use fixture replay when developing the UI without a live agent:

convoy connect --stream fixtures/claude-code-review.jsonl

Notes

connect is long-running. For durable team workers, see Running the CLI long-term.
Executable runtimes today are Claude Code, Codex, and OpenCode; see the Roadmap for per-runtime capabilities and the status of others.