The project is currently under heavy development, so expect a lot of changes and breaking changes. v2.0.0 is coming soon with a managed private alpha. If you want to be notified when we release, please fill this survey here.

Create environment file and update it with the required secret variables.

# Setup environment files
cp .env.local .env

Ensure you have the following tools installed and configured:

• bun - Package manager
  • Install via curl: curl -fsSL https://bun.com/install | bash
  • Install specific version (check .bun-version file): curl -fsSL https://bun.com/install | bash -s "bun-v1.3.1"
  • For other installation methods see Bun installation
• Docker Desktop or OrbStack - Required for running PostgreSQL and Nextjs locally
  • Docker Desktop - Traditional Docker solution
  • OrbStack - Lightweight, faster alternative for macOS (Recommended)
• just - Command runner for project tasks
  • Install via Homebrew: brew install just
  • Or see alternative installation methods
• nvm (Node Version Manager) - Optional, only needed if running linting/tests locally
  • Install from github.com/nvm-sh/nvm
  • The project includes a .nvmrc file to automatically use Node.js 22.20.0
• GitHub OAuth App - For user authentication and accessing user repositories (import functionality)
  1. Go to GitHub Developer Settings
  2. Click OAuth Apps → New OAuth App
  3. Fill in the application details:
     • Application name: Kosuke Core Local (or your preferred name)
     • Homepage URL: http://localhost:3000
     • Authorization callback URL: https://YOUR_CLERK_DOMAIN/v1/oauth_callback (you'll get this from Clerk in the next step)
  4. Click Register application
  5. Copy the Client ID (you'll need this for Clerk setup)
  6. Click Generate a new client secret and copy it immediately (you'll need this for Clerk setup)
  7. Keep this tab open - you'll configure the callback URL after setting up Clerk
• GitHub App - For Kosuke organization operations (creating repos, pull/push etc.)
  1. Go to your organization settings: https://github.com/organizations/YOUR-ORG/settings/apps
  2. Click New GitHub App
  3. Configure the app with required permissions:
     • Repository permissions: Contents (Read & Write), Administration (Read & Write), Pull requests (Read & Write)
     • Organization permissions: Members (Read-only)
  4. Generate a private key (download the .pem file)
  5. Install the app on your organization
  6. Get your credentials and add to .env:
     • GITHUB_APP_ID - Found on your app's settings page
     • GITHUB_APP_PRIVATE_KEY - The private key content (format with \n for newlines)
     • GITHUB_APP_INSTALLATION_ID - From the installation URL
     • GITHUB_WEBHOOK_SECRET - Generate with openssl rand -hex 32
• ngrok (optional) - For testing GitHub webhooks locally
  1. Install ngrok: brew install ngrok or from ngrok.com
  2. Create a free static domain at dashboard.ngrok.com/domains
  3. Start tunnel: ngrok http 3000 --domain=your-domain.ngrok-free.app
  4. Update NEXT_PUBLIC_APP_URL in .env with your static domain
• Clerk Account - Authentication provider
  1. Sign up at clerk.com
  2. Create a new application:
     • Click Create Application
     • Enter your application name
     • Under Sign-in options, select Email, Google and GitHub
     • Click Create Application
  3. Configure GitHub OAuth in Clerk:
     • In your Clerk dashboard, go to Configure → SSO Connections
     • Click on GitHub
     • Toggle Use custom credentials
     • Enter your GitHub Client ID (from step 5 of GitHub OAuth App setup)
     • Enter your GitHub Client Secret (from step 6 of GitHub OAuth App setup)
     • Copy the Authorized redirect URI shown (e.g., https://your-app.clerk.accounts.dev/v1/oauth_callback)
     • Save the settings
  4. Update GitHub OAuth App callback URL:
     • Go back to your GitHub OAuth App settings
     • Update the Authorization callback URL with the redirect URI from Clerk
     • Click Update application
  5. Get Clerk API Keys:
     • Navigate to API Keys in the Clerk dashboard
     • Copy the following keys to your .env file:
       • NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY - Found under "Publishable key"
       • CLERK_SECRET_KEY - Found under "Secret keys"
  6. Enable Organizations in Clerk:
     • Go to Configure → Organizations in the Clerk dashboard
     • Toggle Enable organizations
     • Toggle Allow personal accounts
     • Set max organizations per user (recommended: 10)
     • Keep default roles: org:admin (owner) and org:member (member)
     • Note: The app is organization-first - all projects belong to an organization (either personal workspace or team workspace)

# Start all services (Postgres + Next.js)
just run

The application will be available at:

• Next.js app: http://localhost:3000
• Postgres: localhost:54323

For pre-commits and IDE linting install the dependencies locally:

just install

Note: On first run, you may need to run database migrations. Open a new terminal and run:

# Run database migrations inside the Next.js container
just migrate

The sandbox/ directory contains the infrastructure for preview environments and isolated development sandboxes:

For local development, build the sandbox Docker image:

# Build the local sandbox image
just build-sandbox

This builds kosuke-sandbox-local:latest. The .env.local file is pre-configured to use this image via SANDBOX_IMAGE=kosuke-sandbox-local:latest.

To work with kosuke-cli locally alongside kosuke-core with hot-reload:

# Clone kosuke-cli into the sandbox directory
cd sandbox
git clone https://github.com/Kosuke-Org/cli.git kosuke-cli
cd kosuke-cli && npm install

# Enable hot-reload: watches .ts files → auto-compiles → auto-restarts in preview containers
just watch-agent

The just watch-agent command runs npm run build:watch which watches TypeScript files and auto-compiles to dist/. Preview sandbox containers (created dynamically via src/lib/sandbox/manager.ts) mount sandbox/kosuke-cli/ at /app/kosuke-cli when HOST_PROJECT_PATH is set, and nodemon inside the container auto-restarts the agent on changes. See sandbox/Dockerfile, sandbox/entrypoint.sh, and sandbox/scripts/start-agent.sh for implementation details.

• If it is needed for local development, add it to .env.local
• If it is a NEXT_PUBLIC variable, add it in .env.prod.public
• If it is a server-side variable with a non-secret value, add it in .env.prod
• If it is a server-side variable with a secret value, add it in .env.prod with the syntax VARIABLE=${VARIABLE}, then add the variable in the GitHub kosuke-core repo using the dedicated GitHub workflow: Actions > Add secret > Run workflow

Kosuke is licensed under the MIT License.

For questions or support, you can create an issue in the repo or drop me a message at filippo.pedrazzini (at) kosuke.ai