RAZIEL.docs

Self-Hosting

Run Raziel on your own infrastructure — local setup, environment variables, Docker Compose, and production deployment.

Prerequisites

Before you begin, make sure you have the following accounts and tools:

RequirementPurpose
Node.js 20+Runtime for the Next.js app
PostgreSQL 15+Primary database (sessions, projects, secrets)
Clerk accountAuthentication (sign-in, sign-up, org management)
E2B accountManaged sandbox infrastructure
GitHub AppRepository access + deploy key provisioning
GitVersion control (cloning this repo)
npm or pnpmPackage management

Optional for full functionality:

  • A host for the long-lived PTY bridge (required for interactive terminals) — the pty-bridge service in docker-compose.yml
  • Vercel account — recommended deployment target for the Next.js app

Local Setup

1. Clone the repository

git clone https://github.com/your-org/raziel-web.git
cd raziel-web
npm install

2. Create your environment file

cp .env.example .env.local

Fill in the values described in the Environment Variables section below.

3. Set up the database

npx prisma migrate deploy
npx prisma generate

4. Start the development server

npm run dev

The app will be available at http://localhost:3000.

Environment Variables

Authentication (Clerk)

VariableDescriptionWhere to get it
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEYPublic key for the Clerk frontend SDKClerk dashboard → API Keys
CLERK_SECRET_KEYServer-side Clerk secretClerk dashboard → API Keys
CLERK_WEBHOOK_SECRETSigning secret for Clerk user lifecycle webhooksClerk dashboard → Webhooks
NEXT_PUBLIC_CLERK_SIGN_IN_URLPath for the sign-in pageSet to /sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URLPath for the sign-up pageSet to /sign-up

Database

VariableDescriptionWhere to get it
DATABASE_URLPostgreSQL connection stringYour DB provider (Neon, Supabase, local)

E2B Sandboxes

VariableDescriptionWhere to get it
E2B_API_KEYAPI key for provisioning sandboxesE2B dashboard → API Keys
E2B_TEMPLATESandbox template name (default: raziel-agents)E2B dashboard → Templates

GitHub App

VariableDescriptionWhere to get it
GITHUB_APP_IDGitHub App numeric IDGitHub → Settings → Developer settings → GitHub Apps
GITHUB_APP_PRIVATE_KEYPEM private key for the App (newlines as \n)GitHub App → Generate a private key
GITHUB_APP_CLIENT_IDOAuth Client ID for the AppGitHub App settings
GITHUB_APP_CLIENT_SECRETOAuth Client Secret for the AppGitHub App settings
GITHUB_APP_WEBHOOK_SECRETHMAC secret for App webhooksGitHub App settings

PTY Bridge

VariableDescriptionWhere to get it
PTY_BRIDGE_URLWebSocket URL of the PTY bridgeThe pty-bridge service's public domain (e.g. wss://pty.example.com)
PTY_BRIDGE_SECRETShared secret for bridge→API internal callsGenerate with openssl rand -hex 32

Encryption

VariableDescriptionWhere to get it
ENCRYPTION_KEY32-byte hex key for AES-256 encryption of secretsGenerate with openssl rand -hex 32

App URL

VariableDescriptionWhere to get it
NEXT_PUBLIC_APP_URLPublic base URL of the apphttp://localhost:3000 locally; your Vercel URL in production

Optional: AI Summary

VariableDescriptionWhere to get it
ANTHROPIC_API_KEYAnthropic key used for auto-generating session summariesconsole.anthropic.com

Docker Compose Setup

A minimal docker-compose.yml to run Postgres and the app locally:

version: "3.9"
services:
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: raziel
      POSTGRES_PASSWORD: raziel
      POSTGRES_DB: raziel
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://raziel:raziel@db:5432/raziel
      # ... add the rest of your env vars here
    depends_on:
      - db

volumes:
  pgdata:

Run migrations and start:

docker-compose up -d db
DATABASE_URL=postgresql://raziel:raziel@localhost:5432/raziel npx prisma migrate deploy
docker-compose up app

Production Deployment

The root docker-compose.yml runs Postgres, migrations, the app, the PTY bridge and the preview proxy. On Coolify, deploy it as a Docker Compose resource and give the app, pty-bridge and preview-proxy services their own domains; see Deployment for the variables and domain setup.

Option B: Self-Hosted (Server / Kubernetes)

  1. Build the Next.js app: npm run build
  2. Run the server: npm start (listens on port 3000 by default)
  3. Deploy the PTY bridge separately (Node.js process or Docker container)
  4. Use a reverse proxy (nginx, Caddy) to terminate TLS and route traffic

Ensure your environment has outbound internet access to:

  • api.e2b.dev (sandbox lifecycle)
  • api.clerk.com (auth verification)
  • api.github.com (repo + PR operations)

GitHub App Setup

  1. Go to GitHub → Settings → Developer settings → GitHub Apps → New GitHub App
  2. Set Homepage URL to your app's URL
  3. Set Callback URL to https://your-app.com/api/github/callback
  4. Set Webhook URL to https://your-app.com/api/webhooks/github (if using webhooks)
  5. Grant Repository permissions: Contents (Read/Write), Pull requests (Read/Write), Deploy keys (Read/Write), Metadata (Read)
  6. Generate a private key and download the .pem file
  7. Copy the App ID, Client ID, and Client Secret into your env vars

Upgrading and Migrations

After pulling new code:

git pull
npm install
npx prisma migrate deploy   # applies any new DB migrations
npm run build               # verify the build passes

On Vercel, migrations run automatically during the build step (prisma migrate deploy is in the build command). On other platforms, run npx prisma migrate deploy as part of your deployment pipeline before the new code starts receiving traffic.

To check for pending migrations without applying them:

npx prisma migrate status
Self-Hosting · Raziel