Local Development

Getting Started Locally

Prerequisites

• Node.js 22+ and npm
• Git
• Supabase account
• GitHub account (for GitHub App setup)
• OpenRouter account (for AI provider setup)

1. Clone the Repository

git clone https://github.com/chad-syntax/agentsmith.git
cd agentsmith

2. Install Dependencies

npm install

Setup Supabase

1. Create a Supabase Project

1. Go to supabase.com and create a new project
2. Wait for the project to be fully initialized

2. Get API Keys

1. Navigate to Settings > API in your Supabase dashboard
2. Copy the Project URL and anon/public key to your .env.local
3. Copy the jwt secret into your .env.local this is used for the github_webhook service role

3. Set Up Database Schema

The project includes migration files in /supabase/migrations/.

To apply the migrations, use the Supabase CLI:

# Install Supabase CLI (if you haven't already)
npm install -g supabase

# Login to Supabase
supabase login

# Link your project (if you haven't already)
supabase link --project-ref your-project-ref

# Push migrations
supabase db push

4. Configure Authentication

1. In Supabase Dashboard > Authentication > Settings
2. Add your site URL to "Site URL" field
3. Add redirect URLs for OAuth (see GitHub App Setup section)

5. Running Supabase Locally

You can instead run supabase locally by installing the supabase cli and running

supabase start

This command will then output the environment variables you need to supply in your .env.local

GitHub App Setup

Agentsmith requires a GitHub App for repository synchronization and OAuth authentication.

1. Create a GitHub App

1. Go to GitHub > Settings > Developer settings > GitHub Apps
2. Click "New GitHub App"
3. Fill in the following:
   • GitHub App name: Choose a unique name
   • Homepage URL: https://agentsmith.dev (or your domain)
   • Setup URL: https://your-domain.com/github/setup (use http://localhost:3000/github/setup for local development)
   • Webhook URL:
     • For production: https://your-domain.com/api/github/webhook
     • For local development: Use a webhook proxy service like smee.io.
       1. Go to smee.io and create a new channel.
       2. Use the generated Smee channel URL (e.g., https://smee.io/your-unique-channel) as the Webhook URL in your GitHub App settings.
       3. Set SMEE_WEBHOOK_PROXY_URL in your .env.local to the smee channel url
       4. Start the local Smee client to forward these webhooks to your local server by running: npm run smee-proxy:start (this will typically forward to http://localhost:3000/api/github/webhook or as configured in your smee-proxy script).
   • Webhook secret: Generate a secure random string

2. Set Permissions

Configure the following repository permissions:

• Contents: Read & Write
• Metadata: Read-only
• Pull requests: Read & Write
• Issues: Read & Write
• Account Permissions: Read-only (for email address)

3. Subscribe to Events

• Push
• Pull request

4. Generate Private Key

1. Scroll down to "Private keys" section
2. Click "Generate a private key"
3. Download the .pem file
4. Convert to base64: base64 -i path/to/your-key.pem
5. Add the base64 string to your environment variables

5. Configure OAuth Credentials (within the GitHub App)

1. In your GitHub App's settings page, navigate to the OAuth settings or client secrets section.
2. Generate a new client secret.
3. Copy the "Client ID" and the newly generated "Client Secret".
4. Add these to your Supabase project's GitHub auth provider settings and to your .env.local file as SUPABASE_AUTH_GITHUB_CLIENT_ID and SUPABASE_AUTH_GITHUB_SECRET respectively.
5. Ensure the "Authorization callback URL" in your GitHub App's OAuth settings points to your Supabase callback URL: https://your-supabase-project-ref.supabase.co/auth/v1/callback.

Environment Setup

Create a .env file in the root directory with the following variables:

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_JWT_SECRET=your_supabase_jwt_secret

# GitHub App Configuration
GITHUB_APP_ID=your_github_app_id
GITHUB_APP_PRIVATE_KEY=your_github_app_private_key_base64
GITHUB_APP_WEBHOOK_SECRET=your_github_app_webhook_secret
GITHUB_APP_NAME=your_github_app_name
GITHUB_WEBHOOK_SERVICE_USER_ID=your_github_webhook_service_user_id
SMEE_WEBHOOK_PROXY_URL=your_smee_channel_url

# GitHub OAuth (for Supabase Auth)
SUPABASE_AUTH_GITHUB_CLIENT_ID=your_github_oauth_client_id
SUPABASE_AUTH_GITHUB_SECRET=your_github_oauth_client_secret

# Site Configuration
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# Optional: Analytics
NEXT_PUBLIC_POSTHOG_KEY=your_posthog_key
NEXT_PUBLIC_POSTHOG_HOST=your_posthog_host
SENTRY_AUTH_TOKEN=your_sentry_auth_token

# Optional: Cloudflare Turnstile (for anonymous email submission)
NEXT_PUBLIC_CLOUDFLARE_TURNSTILE_SITE_KEY=your_cloudflare_turnstile_site_key
CLOUDFLARE_TURNSTILE_SECRET_KEY=your_cloudflare_turnstile_secret_key

Variables Reference

Start Development Server

npm run dev

Your application will be available at http://localhost:3000.

Run Tests

# Run all tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run specific test
npm run test -- path/to/test.test.ts