open-swe/apps/docs/setup/development.mdx

---
title: "Development Setup"
description: "How to set up Open SWE for development"
---

This guide will walk you through setting up Open SWE for local development. You'll need to clone the repository, install dependencies, configure environment variables, create a GitHub App, and start the development servers.

<Note>
  This setup is for development purposes. For production deployment, you'll need
  to adjust URLs and create separate GitHub Apps for production use.
</Note>

## Prerequisites

Before starting, ensure you have the following installed:

- Node.js (version 18 or higher)
- Yarn (version 3.5.1 or higher)
- Git

## Setup Steps

<Steps>
  <Step title="Clone the Repository">
    Clone the Open SWE repository to your local machine:

    ```bash
    git clone https://github.com/langchain-ai/open-swe.git
    ```
    ```bash
    cd open-swe
    ```

  </Step>

  <Step title="Install Dependencies">
    Install all dependencies using Yarn from the repository root:

    ```bash
    yarn install
    ```

    This will install dependencies for all packages in the monorepo workspace.

  </Step>

  <Step title="Set Up Environment Files">
    Copy the environment example files and configure them:

    ```bash
    # Copy web app environment file
    cp apps/web/.env.example apps/web/.env
    ```
    ```bash
    # Copy agent environment file
    cp apps/open-swe/.env.example apps/open-swe/.env
    ```

    ### Web App Environment Variables (`apps/web/.env`)

    Fill in the following variables (GitHub App values will be added in the next step):

    ```bash Environment Variables [expandable]
    # API URLs for development
    NEXT_PUBLIC_API_URL="http://localhost:3000/api"
    LANGGRAPH_API_URL="http://localhost:2024"

    # Encryption key for secrets (generate with: openssl rand -hex 32)
    SECRETS_ENCRYPTION_KEY=""

    # GitHub App OAuth settings (will be filled after creating GitHub App)
    NEXT_PUBLIC_GITHUB_APP_CLIENT_ID=""
    GITHUB_APP_CLIENT_SECRET=""
    GITHUB_APP_REDIRECT_URI="http://localhost:3000/api/auth/github/callback"

    # GitHub App details (will be filled after creating GitHub App)
    GITHUB_APP_NAME="open-swe-dev" # this must match the name of your GitHub app, excluding spaces
    GITHUB_APP_ID=""
    GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
    ...add your private key here...
    -----END RSA PRIVATE KEY-----
    "

    # List of GitHub usernames that are allowed to use Open SWE without providing API keys
    # This is only used in production. In development every user is an "allowed user".
    # Must be a valid JSON array of strings.
    NEXT_PUBLIC_ALLOWED_USERS_LIST='["your-github-username", "teammate-username"]'
    ```

    ### Agent Environment Variables (`apps/open-swe/.env`)

    Configure the agent environment variables:

    ```bash Environment Variables [expandable]
    # LangSmith tracing & LangGraph platform
    LANGCHAIN_PROJECT="default"
    LANGCHAIN_API_KEY="lsv2_pt_..."  # Get from LangSmith
    LANGCHAIN_TRACING_V2="true"
    LANGCHAIN_TEST_TRACKING="false"

    # LLM Provider Keys (at least one required)
    ANTHROPIC_API_KEY=""  # Recommended - default provider
    OPENAI_API_KEY=""     # Optional
    GOOGLE_API_KEY=""     # Optional

    # Infrastructure
    DAYTONA_API_KEY=""    # Required. For cloud sandboxes

    # Tools
    FIRECRAWL_API_KEY=""  # For URL content extraction

    # GitHub App settings (same as web app)
    GITHUB_APP_NAME="open-swe-dev" # this must match the name of your GitHub app, excluding spaces
    GITHUB_APP_ID=""
    GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
    ...add your private key here...
    -----END RSA PRIVATE KEY-----
    "
    GITHUB_WEBHOOK_SECRET=""  # Will be generated in next step

    # Server configuration
    PORT="2024"
    OPEN_SWE_APP_URL="http://localhost:3000"
    SECRETS_ENCRYPTION_KEY=""  # Must match web app value

    # CI/CD. See the /labs/swe/setup/ci for more information
    SKIP_CI_UNTIL_LAST_COMMIT="true"

    # List of GitHub usernames that are allowed to use Open SWE without providing API keys
    # This is only used in production. In development every user is an "allowed user".
    # Must be a valid JSON array of strings.
    NEXT_PUBLIC_ALLOWED_USERS_LIST='["your-github-username", "teammate-username"]'
    ```

    If you don't set the `NEXT_PUBLIC_ALLOWED_USERS_LIST` environment variable, every user will be required to set their own LLM API keys to use the agent. Additionally, none of the webhook features (triggering new runs by adding labels to GitHub issues, tagging the agent in PR reviews, etc.) will work unless you include the username's of the GitHub users you want to allow access to in the `NEXT_PUBLIC_ALLOWED_USERS_LIST` environment variable (in both web and agent deployments).

    <Tip>
    Generate the `SECRETS_ENCRYPTION_KEY` using: `openssl rand -hex 32`. This key must be identical in both environment files.
    </Tip>

  </Step>

  <Step title="Create GitHub App">
    <Note>
    You'll need to create a **GitHub App** (not a GitHub OAuth App). These are different types of applications with different capabilities. Consider creating separate GitHub apps for development and production environments.
    </Note>

    ### Create the GitHub App

    1. Go to [GitHub App creation page](https://github.com/settings/apps/new)
    2. Fill in the basic information:
       - **GitHub App name**: Your preferred name
       - **Description**: Development instance of Open SWE coding agent
       - **Homepage URL**: Your repository URL
       - **Callback URL**: `http://localhost:3000/api/auth/github/callback`

    ### Configure OAuth Settings

    - ✅ **Request user authorization (OAuth) during installation** - Allows users to log in to the web app
    - ✅ **Redirect on update** - Redirects users back to your app after permission updates
    - ❌ **Expire user authorization tokens** - Keep tokens from expiring

    ### Set Up Webhook

    1. ✅ **Enable webhook**
    2. **Webhook URL**: You'll need to use a tool like ngrok to expose your local server:
       ```bash
       # Install ngrok if you haven't already
       # Then expose your local LangGraph server
       ngrok http 2024
       ```
       Use the ngrok URL + `/webhooks/github` (e.g., `https://abc123.ngrok.io/webhooks/github`)

    3. **Webhook secret**: Generate and save this value:
       ```bash
       openssl rand -hex 32
       ```
       Add this value to `GITHUB_WEBHOOK_SECRET` in `apps/open-swe/.env`

    ### Configure Permissions

    **Repository permissions:**
    - **Contents**: Read & Write
    - **Issues**: Read & Write
    - **Pull requests**: Read & Write
    - **Metadata**: Read only (automatically enabled)

    **Organization permissions:** None

    **Account permissions:** None

    This gif shows how/where to enable the permissions on the GitHub App:
    <iframe
      className="w-full aspect-video rounded-xl"
      src="https://www.youtube.com/embed/rw6ddYmiTMo"
      title="Permissions Walkthrough"
      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
      allowFullScreen
    ></iframe>

    ### Subscribe to Events

    - ✅ **Issues** - Required for webhook functionality
    - ✅ **Pull request review** - Required for PR tagging functionality
    - ✅ **Pull request review comment** - Required for PR tagging functionality
    - ✅ **Issue comment** - Required for PR tagging functionality

    ### Installation Settings

    - **Where can this GitHub App be installed?**:
      - Choose "Any account" for broader testing
      - Or "Only on this account" to limit to your repositories

    ### Complete App Creation

    Click **Create GitHub App** to finish the setup.

    ### Collect App Credentials

    After creating the app, collect the following values and add them to both environment files:

    - **GITHUB_APP_NAME**: The name you chose
    - **GITHUB_APP_ID**: Found in the "About" section (e.g., `12345678`)
    - **NEXT_PUBLIC_GITHUB_APP_CLIENT_ID**: Found in the "About" section
    - **GITHUB_APP_CLIENT_SECRET**:
      1. Scroll to "Client secrets" section
      2. Click "Generate new client secret"
      3. Copy the generated value
    - **GITHUB_APP_PRIVATE_KEY**:
      1. Scroll to "Private keys" section
      2. Click "Generate a private key"
      3. Download the `.pem` file and copy its contents
      4. Format as a single line with `\\n` for line breaks, or use the multiline format shown in the example
    - **GITHUB_APP_REDIRECT_URI**: Should be `http://localhost:3000/api/auth/github/callback` for local development, or `https://your-production-url.com/api/auth/github/callback` for production.
    - **GITHUB_WEBHOOK_SECRET**: Generate and save this value:
      ```bash
      openssl rand -hex 32
      ```
      Add this value to `GITHUB_WEBHOOK_SECRET` in `apps/open-swe/.env` and `apps/web/.env`.

    Below are screenshots showing where in the GitHub App settings you can find the values for the environment variables.

    <Accordion title="GitHub App OAuth Settings">
      The following screenshots show where to find the following values:

      - `GITHUB_APP_ID`
      - `NEXT_PUBLIC_GITHUB_APP_CLIENT_ID`
      - `GITHUB_APP_CLIENT_SECRET`
      - `GITHUB_APP_REDIRECT_URI`
      - `GITHUB_APP_PRIVATE_KEY`

      ![GitHub Secrets Screenshot 1](/images/gh_app_token_screenshot_1.png)
      ![GitHub Secrets Screenshot 2](/images/gh_app_token_screenshot_2.png)
      ![GitHub Secrets Screenshot 3](/images/gh_app_token_screenshot_3.png)
    </Accordion>

    <Tip>
    Keep your GitHub App credentials secure and never commit them to version control. The `.env` files are already included in `.gitignore`.
    </Tip>

  </Step>

  <Step title="Start Development Servers">
    With all environment variables configured, start both development servers:

    **Terminal 1 - Start the LangGraph Agent:**
    ```bash
    # apps/open-swe
    yarn dev
    ```
    This starts the LangGraph server at `http://localhost:2024`

    **Terminal 2 - Start the Web Application:**
    ```bash
    # apps/web
    yarn dev
    ```
    This starts the Next.js web app at `http://localhost:3000`

    <Note>
    Both servers need to be running simultaneously for full functionality. The web app communicates with the LangGraph agent through API calls.
    </Note>

  </Step>
</Steps>

## Verification

Once both servers are running:

1. **Visit the web app**: Navigate to `http://localhost:3000`
2. **Test GitHub authentication**: Try logging in with your GitHub account

<Tip>
  If you encounter issues, check the console logs in both terminal windows for
  error messages. Common issues include missing environment variables or
  incorrect GitHub App configuration.
</Tip>

## Next Steps

- Learn about [Authentication](/labs/swe/setup/authentication) to understand how the GitHub App integration works
- Explore [Usage](/labs/swe/usage/intro) to start using Open SWE for code changes
- Review the [Monorepo Structure](/labs/swe/setup/monorepo) for development best practices