How to Set Up Open SWE for Local Development: A Complete Guide

To set up Open SWE for local development, clone the repository, install dependencies using the uv package manager, configure environment variables in a .env file, expose your local server via ngrok, and run uv run langgraph dev to start the FastAPI server on port 2024.

Open SWE is an agent-as-a-service platform built on the Deep Agents framework and LangGraph that automates software engineering tasks through deterministic agent threads running in isolated sandboxes. Setting up Open SWE for local development requires configuring a Python environment with uv, establishing secure tunnels for webhook testing, and provisioning credentials for GitHub, LangSmith, and optional Slack or Linear integrations. This guide walks through the exact steps to bootstrap your local instance using the source files from the langchain-ai/open-swe repository.

Prerequisites and Architecture Overview

Before installing, understand how Open SWE processes requests. Each incoming event from Slack, Linear, or GitHub creates a deterministic LangGraph thread that executes in an isolated sandbox—a temporary cloud VM where the target repository is cloned and the LLM-driven agent operates.

The local development architecture consists of:

• agent/webapp.py – FastAPI application exposing webhook endpoints and health checks
• agent/server.py – Constructs the Deep Agents graph, handles sandbox creation, and manages the middleware stack
• agent/utils/sandbox.py – Factory that selects the sandbox provider based on the SANDBOX_TYPE environment variable

Step 1: Clone the Repository and Install Dependencies

Start by cloning the repository and creating an isolated Python environment using the modern uv package manager.

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

Create the virtual environment and install all dependencies including development extras:

uv venv
source .venv/bin/activate
uv sync --all-extras

The uv sync command reads dependency specifications from pyproject.toml (lines 8-26), ensuring deterministic environment creation across different machines.

Step 2: Configure Environment Variables

Open SWE requires several API keys and secrets to authenticate with GitHub, LangSmith, and optional messaging platforms. Create a .env file in the project root:

# LangSmith (required for sandbox creation and tracing)

LANGSMITH_API_KEY_PROD="sk-..."
LANGSMITH_TENANT_ID_PROD="..."
LANGSMITH_TRACING_PROJECT_ID_PROD="..."
LANGSMITH_URL_PROD="https://smith.langchain.com"

# GitHub App (required for repository cloning and PR creation)

GITHUB_APP_ID="12345"
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----"
GITHUB_APP_INSTALLATION_ID="67890"
GITHUB_WEBHOOK_SECRET="my-github-secret"

# Optional: Slack integration

SLACK_BOT_TOKEN="xoxb-..."
SLACK_SIGNING_SECRET="my-slack-secret"
SLACK_BOT_USER_ID="U01..."
SLACK_BOT_USERNAME="open-swe"

# Optional: Linear integration

LINEAR_API_KEY="lin-..."
LINEAR_WEBHOOK_SECRET="my-linear-secret"

# Sandbox configuration

SANDBOX_TYPE="langsmith"

The application reads these variables via os.getenv throughout the codebase, particularly in agent/utils/sandbox.py for the SANDBOX_TYPE selector and INSTALLATION.md for the complete variable reference.

Step 3: Expose Local Server with ngrok

Open SWE receives webhooks from external services (GitHub, Slack, Linear) that cannot reach localhost. Use ngrok to create a secure tunnel:

ngrok http 2024 --url https://my-open-swe.ngrok.dev

Note the HTTPS URL provided by ngrok—you will configure this as the webhook URL in your GitHub App, Slack App, and Linear integration settings. The webhook endpoints are defined in agent/webapp.py (lines 41-65), handling routes for /webhooks/github, /webhooks/slack, and /webhooks/linear.

Step 4: Start the LangGraph Development Server

Launch the local development server using the LangGraph CLI:

uv run langgraph dev --no-browser

This command:

1. Loads the graph definition from langgraph.json, which maps the "agent" entry point to agent.server:get_agent
2. Starts the FastAPI application defined in agent/webapp.py (line 57)
3. Binds to port 2024 by default

The server is now ready to receive webhook events forwarded by ngrok and execute agent threads in sandboxes via the LangSmith integration.

Step 5: Verify Your Local Setup

Confirm the server is healthy by accessing the health check endpoint:

curl https://<ngrok-url>/health

You should receive {"status":"healthy"} (implemented in agent/webapp.py, lines 66-71).

Test the full webhook pipeline by simulating a Slack event:

curl -X POST https://<ngrok-url>/webhooks/slack \
  -H "Content-Type: application/json" \
  -H "X-Slack-Signature: <computed-signature>" \
  -d '{"type":"event_callback","event":{"type":"app_mention","channel":"C123","user":"U456","text":"@open-swe list files","ts":"1690000000.000200"}}'

If configured correctly, the bot will react with 👀 and initiate a LangGraph run visible in your LangSmith tracing project.

Advanced Local Development Workflows

Programmatic Sandbox Testing

For unit testing or debugging sandbox behavior without triggering full webhook flows, instantiate sandboxes directly:

from agent.utils.sandbox import create_sandbox

sandbox = create_sandbox()  # Uses SANDBOX_TYPE env var (default: langsmith)

print("Sandbox ID:", sandbox.id)

# SandboxBackendProtocol implements .execute(), .list_files(), etc.

Direct Agent Invocation

Bypass the HTTP layer for rapid prototyping by invoking the agent graph directly:

from agent.server import get_agent
from langgraph_sdk import get_client

client = get_client()
thread_id = "dev-thread-123"

config = {
    "configurable": {"thread_id": thread_id, "__is_for_execution__": True},
    "metadata": {}
}
agent = await get_agent(config)
run = await client.runs.create(
    thread_id,
    "agent",
    input={"messages": [{"role": "user", "content": "List the files in the repo root"}]},
    config=config,
)
print("Run ID:", run["run_id"])

Summary

• Clone the langchain-ai/open-swe repository and install dependencies using uv sync --all-extras to ensure deterministic environment creation.
• Configure a .env file with LangSmith and GitHub App credentials required for sandbox creation and repository access.
• Tunnel your local port 2024 via ngrok to receive webhooks from external services like GitHub, Slack, and Linear.
• Launch the development server with uv run langgraph dev --no-browser, which loads the graph from langgraph.json and starts the FastAPI app in agent/webapp.py.
• Verify your setup using the /health endpoint and test webhooks to ensure the agent correctly initializes LangGraph threads in isolated sandboxes.

Frequently Asked Questions

What is the difference between agent/webapp.py and agent/server.py?

agent/webapp.py implements the FastAPI application that exposes HTTP endpoints including webhook handlers for Slack, Linear, and GitHub, plus health checks. agent/server.py constructs the LangGraph Pregel graph that defines the agent's logic, manages sandbox creation via create_sandbox(), and handles repository cloning. The webapp receives external events and delegates execution to the server graph.

Can I use a different tunnel service instead of ngrok?

Yes, any service that forwards HTTP traffic from a public URL to localhost:2024 works, such as Cloudflare Tunnel, Tailscale Funnel, or localtunnel. Configure your GitHub App, Slack App, and Linear integration settings to point to your tunnel URL instead of the ngrok domain. Ensure the tunnel supports HTTPS, as webhook providers typically require secure endpoints.

Which environment variables are strictly required to start the server?

The minimum required variables are those for LangSmith (LANGSMITH_API_KEY_PROD, LANGSMITH_TENANT_ID_PROD, LANGSMITH_TRACING_PROJECT_ID_PROD, LANGSMITH_URL_PROD) and GitHub App credentials (GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_APP_INSTALLATION_ID, GITHUB_WEBHOOK_SECRET). These enable sandbox creation and repository access. Slack and Linear variables are optional unless testing those specific integrations.

How do I switch between different sandbox providers?

Set the SANDBOX_TYPE environment variable in your .env file to one of the supported values: langsmith (default), daytona, modal, runloop, or local. The factory function in agent/utils/sandbox.py reads this variable and instantiates the appropriate backend implementing the SandboxBackendProtocol. Each provider offers different trade-offs in startup time, persistence, and resource limits for executing agent code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}