Self-hosting DevFleet

An end-to-end guide on how to self-host DevFleet – the open-source AI-powered coding agent runner.

You can self-host DevFleet on your own servers and cloud infrastructure for greater control over your data and workflows. This guide will walk you through the entire process of setting up DevFleet on your own servers.

Prerequisites

Before you begin, make sure you have the following:

• A GitHub  account
• An Anthropic  account
• An E2B  account
• A Vercel  account
• Docker  installed (for local PostgreSQL)
• ngrok  account (for webhook development)

You’ll also need a custom domain for your DevFleet instance.

In this guide, we’ll use app.acme.com as a placeholder for your custom domain.

Step 1: Local Setup

First, you’ll need to clone the DevFleet repo and install the dependencies.

Clone the repo

Clone the DevFleet repo  into a public GitHub repository.

git clone https://github.com/dev-fleet/devfleet.git

Install dependencies

DevFleet uses pnpm as its package manager. If you don’t have pnpm installed, install it first:

npm install -g pnpm

Then install the dependencies:

pnpm install

Set up environment variables

Navigate to apps/web and copy the example environment file:

cp apps/web/.env.example apps/web/.env

You’ll fill in the environment variables in the following steps.

Step 2: Set up PostgreSQL Database

DevFleet uses PostgreSQL as its primary database. For local development, we provide a Docker Compose configuration using the Supabase Postgres image.

Start the database

Run the following command to start the PostgreSQL container:

npm run db:docker:up

This starts a PostgreSQL 15 instance on port 5432 with the password postgres.

Configure the database URL

Add the following to your .env file:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres

Run database migrations

Run Drizzle migrations:

npm run db:migrate

For development, you can push schema changes directly:

npm run db:dev:push

Step 3: Set up GitHub App

DevFleet requires a GitHub App to interact with repositories, handle webhooks, and perform Git operations.

Create a new GitHub App

1. Go to GitHub App settings 

2. Fill in the following details:

   • GitHub App name: Choose a name (e.g., “DevFleet - Your Company”)
   • Homepage URL: https://app.acme.com (or http://localhost:3001 for local dev)
   • Callback URL: https://app.acme.com/api/github-app/callback
   • Setup URL (optional): Leave blank
   • Webhook URL: https://app.acme.com/api/github-app/webhook
   • Webhook secret: Generate a secure secret (e.g., openssl rand -hex 32)

3. Check “Request user authorization (OAuth) during installation”

Set repository permissions

Under Repository permissions, set:

Subscribe to events

Under Subscribe to events, check:

• Issue comment
• Issues
• Pull request

Generate credentials

After creating the app:

1. Copy the App ID and set it in .env:

   GITHUB_APP_ID=<App ID>

2. Copy the Client ID and set it in .env:

   GITHUB_APP_CLIENT_ID=<Client ID>

3. Generate a Client secret, copy it, and set it in .env:

   GITHUB_APP_CLIENT_SECRET=<Client Secret>

4. Set your Webhook secret in .env:

   GITHUB_APP_WEBHOOK_SECRET=<Webhook Secret>

5. Generate a Private key, download the .pem file, and convert it to base64:

   npx base64key ~/Downloads/your-app-name.pem | pbcopy

   Then set it in .env:

   GITHUB_APP_PRIVATE_KEY=<base64-encoded private key>

6. Set the install URL in .env:

   NEXT_PUBLIC_GITHUB_APP_INSTALL_URL=https://github.com/apps/<your-app-name>/installations/new

Step 4: Set up GitHub OAuth

DevFleet uses GitHub OAuth for user authentication (separate from the GitHub App).

Create OAuth App

1. Go to OAuth Apps settings 

2. Fill in the following:

   • Application name: Choose a name (e.g., “DevFleet Auth”)
   • Homepage URL: https://app.acme.com
   • Authorization callback URL: https://app.acme.com/api/auth/callback/github

3. After creating, copy the credentials and set them in .env:

   AUTH_GITHUB_ID=<Client ID>
   NEXT_PUBLIC_AUTH_GITHUB_ID=<Client ID>
   AUTH_GITHUB_SECRET=<Client Secret>

Step 5: Set up Authentication Secret

DevFleet uses Better Auth for authentication. Generate a secure secret:

openssl rand -base64 32

Set it in your .env file:

BETTER_AUTH_SECRET=<your-generated-secret>

Step 6: Set up Encryption Key

DevFleet encrypts sensitive data like API keys. Generate an encryption key:

openssl rand -base64 32

Set it in your .env file:

ENCRYPTION_KEY=<your-generated-key>

Step 7: Set up AI Provider

Anthropic (recommended)

1. Go to Anthropic Console 
2. Create a new API key
3. Set it in your .env file:

   ANTHROPIC_API_KEY=<your-anthropic-key>

Step 8: Set up E2B

DevFleet uses E2B  to run code in isolated sandboxes.

1. Sign up at E2B 
2. Get your API key from the dashboard
3. Set it in your .env file:

   E2B_API_KEY=<your-e2b-key>

Build the E2B template (optional)

If you need to customize the sandbox environment:

cd apps/infra
e2b template build

Step 9: Set up Webhooks (Local Development)

For local development, you need a public URL to receive GitHub webhooks.

Set up ngrok

1. Sign up at ngrok  and download the binary

2. Authenticate ngrok with your token

3. Start the tunnel:

   ngrok http 3001 --url your-subdomain.ngrok-free.app

4. Update your GitHub App webhook URL to use the ngrok URL:

   https://your-subdomain.ngrok-free.app/api/github-app/webhook

5. Also add the local callback URL to your GitHub OAuth app:

   http://localhost:3001/api/auth/callback/github

Step 10: Run the Development Server

With all environment variables configured, you can now start DevFleet:

Start the application

npm run dev

Open http://localhost:3001  to see DevFleet running.

Step 11: Deploy to Production

Once you’ve verified everything works locally, you can deploy to production.

Environment Variables Reference

Here’s a complete list of all environment variables:

Caveats

This guide is meant to be a starting point for self-hosting DevFleet. The current setup depends on the following services:

• E2B  for sandboxed code execution
• Vercel  for hosting
• GitHub  for repository access and authentication

Troubleshooting

Webhook not receiving events

1. Verify your ngrok tunnel is running (local dev)
2. Check the webhook secret matches in GitHub and .env
3. Verify the webhook URL is correct in GitHub App settings

Authentication issues

1. Ensure both GitHub OAuth callback URLs are set correctly
2. Verify BETTER_AUTH_SECRET is set
3. Check that AUTH_GITHUB_ID and AUTH_GITHUB_SECRET are correct

Database connection errors

1. Verify PostgreSQL is running: docker ps
2. Check DATABASE_URL format is correct
3. Run migrations: npm run db:migrate

Need help? Open an issue  on GitHub.