Installation & Setup

Set up CodeCourier for local development. Covers system requirements, environment variables, Convex, Clerk, E2B, and Trigger.dev configuration.

10 min read
installationsetupenvironment

This guide covers everything you need to run CodeCourier locally for development. CodeCourier is a Next.js application backed by Convex, Clerk, E2B, and Trigger.dev. Each service requires its own configuration, but once set up, the local development experience is fully functional with hot reloading and real-time data.

System requirements

  • Node.js - Version 20.9.0 or later (required by Clerk SDK)
  • Package manager - Bun (recommended, used in the project scripts) or npm/yarn/pnpm
  • Git - For cloning the repository and managing branches
  • Operating system - macOS, Linux, or Windows (with WSL recommended for the best experience)

Bun is optional

While the project is configured for Bun (the package name is bun-nextjs-convex-clerk), all standard npm commands work as well. The instructions below show both options.

Clone and install

1

Clone the repository

Terminal
git clone https://github.com/your-org/codecourier.git
cd codecourier
2

Install dependencies

Terminal
bun install

This installs all production and development dependencies including Next.js, Convex, Clerk, the E2B SDK, Trigger.dev SDK, Tailwind CSS, Radix UI, shadcn/ui, Framer Motion, and testing tools (Vitest, Playwright).

Environment variables

Create a .env.local file in the project root. The repository includes a .env.example file with all supported variables. Copy it as your starting point:

Terminal
cp .env.example .env.local

The following variables are required for local development:

Convex

.env.local
# Your Convex deployment URL (shown after running npx convex dev)
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud

# Convex site URL (used by Trigger.dev for HTTP callbacks)
CONVEX_SITE_URL=https://your-deployment.convex.site

Clerk authentication

.env.local
# Clerk publishable key (client-side, starts with pk_test_ or pk_live_)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx

# Clerk secret key (server-side, starts with sk_test_ or sk_live_)
CLERK_SECRET_KEY=sk_test_xxx

# Clerk JWT issuer domain (found in Clerk dashboard > JWT Templates)
CLERK_JWT_ISSUER_DOMAIN=https://your-clerk-domain.clerk.accounts.dev

# Clerk webhook signing secret (for Convex HTTP webhook handler)
CLERK_WEBHOOK_SECRET=whsec_xxx

Trigger.dev

.env.local
# Shared secret for authenticating callbacks between Trigger.dev and Convex
TRIGGER_CALLBACK_SECRET=your-random-secret-string

Generate a strong callback secret

The TRIGGER_CALLBACK_SECRET is used to verify that incoming HTTP requests to Convex genuinely originate from your Trigger.dev jobs. Use a cryptographically random string (at least 32 characters). You can generate one with openssl rand -hex 32.

Optional variables

.env.local
# PostHog analytics (optional)
# NEXT_PUBLIC_POSTHOG_KEY=phc_xxx
# NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

# Meta/Facebook Pixel (optional)
# NEXT_PUBLIC_META_PIXEL_ID=123456789

# Google Ads conversion tracking (optional)
# NEXT_PUBLIC_GOOGLE_ADS_ID=AW-123456789

Service setup

1

Set up Convex

Convex is the database and backend runtime for CodeCourier. Start the Convex development server, which syncs your local schema and functions to a development deployment:

Terminal
npx convex dev

On first run, the Convex CLI will prompt you to log in and create a new project. After setup, it prints your deployment URL - copy this into your .env.local as NEXT_PUBLIC_CONVEX_URL.

The Convex dev server watches for changes to files in the convex/ directory and automatically pushes schema and function updates. Keep this terminal running during development.

Convex environment variables

Your Convex deployment also needs environment variables for features like Clerk webhook verification. Set them in the Convex dashboard under your project’s Settings > Environment Variables. At minimum, configure CLERK_WEBHOOK_SECRET and TRIGGER_CALLBACK_SECRET there.
2

Configure Clerk authentication

Create a Clerk application at dashboard.clerk.com:

  1. Create a new application and enable your desired sign-in methods (Google, GitHub, email, etc.)
  2. Copy the Publishable Key and Secret Key from the API Keys page into your .env.local
  3. Set up a JWT Templatefor Convex. In the Clerk dashboard, navigate to JWT Templates, create a new template named “convex”, and configure the issuer and audience fields as documented in the Convex + Clerk integration guide
  4. Copy the JWT issuer domain into CLERK_JWT_ISSUER_DOMAIN
  5. Set up a Webhook endpoint pointing to your Convex site URL (e.g., https://your-deployment.convex.site/clerk-webhook). Enable user events (user.created, user.updated, user.deleted). Copy the signing secret into CLERK_WEBHOOK_SECRET
3

Set up E2B sandbox access

E2B provides the cloud sandboxes where AI agents execute. Configuration is done at the project level inside the CodeCourier UI (Project Settings > API Keys), not as a local environment variable. However, to verify your E2B setup during development:

  1. Create an account at e2b.dev and obtain your API key from the dashboard
  2. After starting CodeCourier, navigate to Project Settings and add your E2B API key in the API Keys section

The E2B SDK (e2b package) is already included in the project dependencies. Sandbox templates (which define the base environment and pre-installed tools) are configured per-workflow and managed through the CodeCourier UI.

4

Connect Trigger.dev

Trigger.dev handles background job execution for sandbox provisioning, workflow runs, and issue sessions. For local development:

  1. Sign up at trigger.dev and create a new project
  2. Install the Trigger.dev CLI globally or use npx:
Terminal
npx trigger.dev@latest dev

This starts the Trigger.dev dev server, which connects to the Trigger.dev cloud to receive and process jobs locally. The project includes a trigger.config.ts file that defines all registered tasks.

Trigger.dev is optional for UI development

If you are only working on the frontend and do not need to test actual sandbox execution, you can skip the Trigger.dev setup. The UI will still load and display data from Convex - runs and sandboxes just will not execute.

Start the development server

With Convex dev running in one terminal, start the Next.js development server in another:

Terminal
bun dev

The application starts at http://localhost:3000. You should see the Clerk sign-in page. After authenticating, you will be directed to create your first project or join an existing one.

Verify the installation

Run through this checklist to confirm everything is working:

  1. Authentication: You can sign in and out through Clerk. Your user appears in the Convex dashboard under the users table.
  2. Project creation: You can create a new project. Check that the projects, projectMembers, and projectSettings tables populate in Convex.
  3. Real-time updates: Open two browser tabs on the same project. Create a workflow in one tab and confirm it appears instantly in the other.
  4. API key storage: Add an E2B API key in project settings and verify it appears with only the last four characters visible.

Running tests

CodeCourier includes both unit tests (Vitest) and end-to-end tests (Playwright):

Terminal
# Unit tests
npm run test

# Unit tests with watch mode
npm run test:watch

# Unit tests with coverage report
npm run test:coverage

# End-to-end tests (requires the dev server running)
npm run test:e2e

# E2E tests with interactive UI
npm run test:e2e:ui

Troubleshooting

Convex dev fails to start

Ensure you are logged in to the Convex CLI (npx convex login) and that your convex.json file points to a valid project. If you see schema validation errors, check that all files in the convex/ directory compile without TypeScript errors.

Clerk authentication redirects loop

Verify that NEXT_PUBLIC_CLERK_PUBLISHABLE_KEYmatches your Clerk application environment (test vs. production). Ensure the JWT template in Clerk is named “convex” and the issuer domain in CLERK_JWT_ISSUER_DOMAIN matches exactly.

Sandbox creation fails

Check that your E2B API key is correctly configured in project settings (not in .env.local - E2B keys are stored per-project in Convex). Verify the Trigger.dev dev server is running and connected. Check the Trigger.dev dashboard for job execution logs.

Type checking errors

Run the type checker to find issues:

Terminal
npm run typecheck

The project uses TypeScript 5.9+ with strict mode. Convex generates types automatically in convex/_generated/ - if these are missing, make sure npx convex dev has run at least once.

Next steps

Core Concepts

Understand the data model and how CodeCourier's features connect.

Your First Project

Detailed walkthrough of configuring a project for real-world use.