Self-Hosting Sweep with Docker and Private GitHub App Credentials: The Engineering Guide

Engineering teams operating in heavily regulated industries—such as fintech, healthcare, and enterprise infrastructure—frequently encounter a strict architectural barrier when adopting autonomous coding agents: corporate compliance policies forbid sending proprietary code to multi-tenant third-party clouds. Sweep addresses this friction through its open-source backend architecture. By deploying Sweep inside a private virtual private cloud (VPC) or on-premises environment using Docker and configuring a dedicated, private GitHub App, DevOps engineers can automate the full issue-to-pull-request lifecycle while keeping raw codebase indexing, git operations, and repository secrets entirely within their corporate security perimeter.

This guide provides an end-to-end technical blueprint for deploying, configuring, and operating a self-hosted Sweep instance, including infrastructure sizing, private GitHub App credential management, webhook networking, and lifecycle operations.

Architectural Overview: How Self-Hosted Sweep Operates

To operate Sweep reliably on-premises, engineering teams must understand how its internal services interact with GitHub and large language model (LLM) providers:

[GitHub / GitHub Enterprise]
       |
       |  1. Webhook Payload (issues, PR comments)
       v
[Reverse Proxy / Ingress (TLS Termination & IP Whitelist)]
       |
       |  2. HTTP Port 8080 (HMAC Signature Verified)
       v
[Sweep Container (`sweepai/sweep`)]
  ├── Fast Webhook Handler (FastAPI / Uvicorn)
  ├── Task Queue & Job Dispatcher (Embedded Redis + Background Workers)
  ├── Code Intelligence Engine (Ripgrep + GitHub Linguist + AST Parsers)
  └── Workspace Cache Mount (`/mnt/caches`)
       |
       |  3. Sanitized Prompt Context
       v
[Enterprise LLM API (OpenAI / Anthropic / Private Gateway)]
       |
       |  4. Code Diff & Plan Synthesis
       v
[Sweep Git Engine]
       |
       |  5. Authenticated Git Push & PR Creation (GitHub App RSA PEM)
       v
[GitHub Repository (New Branch & Pull Request)]

1. Inbound Webhook Routing: GitHub sends event notifications (such as issues.opened or pull_request_review_comment.created) to the Sweep container on port 8080. Every incoming payload is cryptographically validated using HMAC-SHA256 against a shared WEBHOOK_SECRET.
2. Asynchronous Execution Queue: Because GitHub enforces a strict 10-second timeout for webhook acknowledgments, Sweep immediately queues the payload into an internal Redis-backed task pipeline and returns HTTP 200 OK.
3. Local Codebase Indexing: The container executes search tools, including ripgrep for regex and symbol searches, github-linguist for language classification, and tree-sitter AST parsers across local repository working copies. Working states and embeddings are persisted in /mnt/caches.
4. LLM Orchestration: Sweep formats focused code snippets and instructions, querying configured LLM endpoints (OPENAI_API_KEY or ANTHROPIC_API_KEY). Only sanitized context prompts leave the host; the full repository is never mirrored or stored externally.
5. Git Operations & GitHub App Authentication: Sweep signs a JSON Web Token (JWT) using its RSA private key (GITHUB_APP_PEM) to mint short-lived installation access tokens. It clones the target repository, branches off the default branch, applies synthesized diffs, commits changes under the bot identity, and creates an upstream pull request.

System Requirements and Prerequisites

Sweep performs intensive multi-process workloads—running git operations, background indexing, ripgrep parsing, and concurrent HTTP requests within the container.

Hardware Sizing

• Operating System: Ubuntu 22.04 LTS, Ubuntu 24.04 LTS, or Enterprise Linux (RHEL 9 / Rocky Linux).
• CPU: Minimum 4 vCPUs (dedicated cores recommended for concurrent repository search).
• RAM: 32 GB RAM minimum (16 GB may cause out-of-memory errors during large repo AST indexing).
• Disk Storage: 200 GB SSD or NVMe storage (fast I/O is critical for git checkouts and persistent caches).
• Baseline Instance Reference: AWS t3.xlarge, GCP e2-standard-8, or equivalent on-premise hypervisor.

Software & Network Prerequisites

• Docker Engine 24.0+ and Docker Compose v2.20+.
• Outbound HTTPS (TCP port 443) connectivity to your LLM API endpoint (e.g., api.openai.com or api.anthropic.com).
• Inbound HTTPS accessibility for GitHub webhooks, either via a public domain backed by a corporate reverse proxy (Nginx, Caddy, Cloudflare Tunnel) or intranet connectivity if integrated with GitHub Enterprise Server (GHES).

Step 1: Register and Configure the Private GitHub App

A private GitHub App provides scoped authentication, ensuring Sweep only accesses explicitly permitted repositories without using broad personal access tokens.

1. Create the GitHub App

1. Log in to GitHub, navigate to your Organization Settings, and select Developer settings > GitHub Apps > New GitHub App.
2. Configure basic application metadata:
   • GitHub App name: A unique identifier for your team (e.g., Corp-Internal-Sweep).
   • Homepage URL: Your organization URL or internal documentation link.
   • Callback URL: Optional (leave empty if not configuring user authorization flows).

2. Configure Webhooks

• Webhook URL: Enter your external or ingress endpoint pointing to Sweep (e.g., https://sweep.internal.corp.com/ or http://<YOUR_HOST_IP>:8080).
• Webhook secret: Generate a secure random string using openssl rand -hex 32 and store it securely.

3. Grant Repository Permissions

Configure the following granular permissions under Repository permissions:

4. Subscribe to Webhook Events

Under Subscribe to events, select:

• Issues (opened, edited, labeled, assigned)
• Issue comment (created, edited)
• Pull request (opened, synchronized, review requested)
• Pull request review comment (created, edited)
• Check run (completed)

5. Generate and Download the Private Key

1. Set Where can this GitHub App be installed? to Only on this account (Private).
2. Click Create GitHub App.
3. On the application settings page, record your numeric App ID (e.g., 123456).
4. Scroll to the Private keys section and click Generate a private key. Download the resulting .pem file.
5. In the left navigation menu, select Install App, choose your organization, and select the specific repositories Sweep should monitor.

Step 2: Configure Environment Variables

Create your project deployment directory and initialize an environment file named .env.

mkdir -p /opt/sweep && cd /opt/sweep
git clone https://github.com/sweepai/sweep.git
cd sweep

Construct your .env file using the parameters retrieved in Step 1:

# GitHub App Authentication
GITHUB_APP_ID=123456
GITHUB_BOT_USER=corp-internal-sweep[bot]
WEBHOOK_SECRET=your_generated_webhook_secret_here

# Format the RSA Private Key as a single line with escaped newline characters,
# or preserve the full multi-line block as read by Docker Compose:
GITHUB_APP_PEM="-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----\n"

# Sweep License Key
# Trial keys are available for evaluation; enterprise keys require Sweep team contact
LICENSE_KEY=ABCDE-FGHIJ-KLMNO-PQRST-UVWXY

# LLM Inference Providers
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Container Environment
PORT=8080
WORKERS=3

Security Note on PEM Formatting: If passing GITHUB_APP_PEM as a single environment line, replace physical line breaks with \n. Alternatively, configure your deployment script to read the .pem file directly into the environment variable using GITHUB_APP_PEM="$(cat /opt/sweep/github-app.pem)".

Step 3: Deploy Sweep via Docker Compose

Sweep provides an official multi-stage Dockerfile and docker-compose.yml configured to build a self-contained runtime containing Python 3.10, Redis, ripgrep, and language analyzers.

Inspect the core services configuration in docker-compose.yml:

services:
  hosted:
    build:
      context: .
      dockerfile: Dockerfile
      target: base
    image: sweepai/sweep:local
    container_name: webhook
    env_file:
      - .env
    volumes:
      - .:/app
      - /mnt/caches:/mnt/caches
    ports:
      - "${PORT:-8080}:8080"
    restart: unless-stopped
    command: >
      sh -c ". bin/startup.sh"

Launch the Container Stack

Ensure the host cache directory exists and start the service in detached mode:

sudo mkdir -p /mnt/caches
sudo chown -R 1000:1000 /mnt/caches

# Build and start the hosted backend
docker compose up --build -d hosted

Verify that the container is healthy and actively listening:

# Check container status
docker ps -f name=webhook

# Inspect real-time initialization logs
docker compose logs -f hosted

You should observe redis-server initializing, followed by Uvicorn starting worker processes listening on 0.0.0.0:8080.

Step 4: Configure Network Ingress and Webhook Security

In production environments, exposing port 8080 directly without transport layer security (TLS) is unsafe. You should place Sweep behind a reverse proxy (such as Nginx) configured with TLS termination and IP address filtering.

Production Nginx Reverse Proxy Configuration

upstream sweep_backend {
    server 127.0.0.1:8080;
    keepalive 32;
}

server {
    listen 443 ssl http2;
    server_name sweep.internal.corp.com;

    ssl_certificate /etc/ssl/certs/sweep.internal.corp.com.crt;
    ssl_certificate_key /etc/ssl/private/sweep.internal.corp.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # Restrict ingress traffic to official GitHub Webhook IP blocks
    # Fetch current CIDR ranges from https://api.github.com/meta ("hooks")
    allow 192.30.252.0/22;
    allow 185.199.108.0/22;
    allow 140.82.112.0/20;
    allow 143.55.64.0/20;
    # Internal corporate subnets for testing
    allow 10.0.0.0/8;
    deny all;

    client_max_body_size 50M;

    location / {
        proxy_pass http://sweep_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        proxy_connect_timeout 10s;
        proxy_read_timeout 120s;
        proxy_send_timeout 120s;
    }
}

Note: If your team hosts GitHub Enterprise Server (GHES) entirely within an air-gapped intranet, no public internet ingress is required. Simply route internal webhook traffic from GHES to the Sweep container IP address over port 8080 or an internal HTTPS endpoint.

Step 5: End-to-End Workflow Verification

Once the container and ingress are running, verify the automated issue-to-pull-request pipeline:

1. Trigger via GitHub Issue: Open a repository where the GitHub App is installed. Create a new issue with a title prefixed by Sweep:, for example:

   Title: Sweep: Add input validation and test cases for email parser
   Body: Please validate RFC 5322 compliance in utils/email.py and add corresponding pytest unit tests.
   

2. Observe Webhook Reception: In your server console, watch the container logs:

   docker compose logs -f hosted
   

   Sweep will log the verified webhook event, mint an installation access token, and initiate codebase search.
3. Review Execution Plan: Sweep will comment on the GitHub issue, detailing the affected files, intended architectural modifications, and proposed patch plan.
4. Inspect Generated Pull Request: Within two to five minutes, Sweep will push a new branch (sweep/add-input-validation...) and open a Pull Request linking back to the issue with a structured description of the changes.
5. Interactive Review Feedback: Leave a line-level review comment on the PR diff (e.g., "Sweep: Use regex rather than split here"). Sweep will pick up the review webhook, apply the requested changes, and push an incremental commit.

Lifecycle Operations: Zero-Downtime Redeployment and Maintenance

Because Sweep manages long-running background tasks—such as full repository indexing, multi-step LLM reasoning chains, and git pushes—executing docker compose down will abruptly kill in-flight jobs.

Graceful Redeployment

The Sweep repository includes a dedicated redeployment utility:

# Pull upstream updates or local modifications
git pull origin main

# Execute graceful restart
bash bin/redeploy.sh

The script manages worker process termination gracefully, allowing existing task execution to complete before restarting the container stack.

Cache Hygiene and Disk Maintenance

Over time, indexing multiple enterprise repositories can accumulate large working trees in /mnt/caches. Schedule a monthly maintenance cron job to purge obsolete cache directories:

# Remove cache trees older than 30 days
find /mnt/caches -mindepth 1 -maxdepth 2 -type d -mtime +30 -exec rm -rf {} +

# Clean dangling Docker build artifacts
docker image prune -f

Architectural Comparison: Self-Hosted vs. Cloud SaaS

Production Recommendations for Enterprise DevOps

1. Model Selection: Self-hosted Sweep requires top-tier reasoning models to generate accurate multi-file edits. Configure Anthropic Claude 3.5 Sonnet or OpenAI GPT-4o keys. Attempting to point Sweep to undersized local open-source models (such as 7B/8B parameter models) often results in failed multi-file diff formatting and syntax errors.
2. Maintenance Expectations: Sweep's open-source repository established an early paradigm for autonomous GitHub coding agents, while its commercial team subsequently diversified toward IDE-centric extensions. Engineering teams adopting self-hosted Sweep should treat the Docker backend as an internally maintained platform, dedicating engineering capacity to maintain dependency updates and custom prompts.
3. Credential Rotation: Establish a 90-day rotation cadence for both the GitHub App RSA private key (.pem) and the WEBHOOK_SECRET to align with enterprise SOC 2 and ISO 27001 credential lifecycle policies.

References

• GitHub - sweepai/sweep: Sweep: AI coding assistant for JetBrains
• Self-Hosting Sweep via Docker
• Sweep Docker Compose Configuration
• Sweep Backend Dockerfile
• Registering a GitHub App - GitHub Docs