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:
| Requirement | Purpose |
|---|---|
| Node.js 20+ | Runtime for the Next.js app |
| PostgreSQL 15+ | Primary database (sessions, projects, secrets) |
| Clerk account | Authentication (sign-in, sign-up, org management) |
| E2B account | Managed sandbox infrastructure |
| GitHub App | Repository access + deploy key provisioning |
| Git | Version control (cloning this repo) |
npm or pnpm | Package management |
Optional for full functionality:
- A host for the long-lived PTY bridge (required for interactive terminals) — the
pty-bridgeservice indocker-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 install2. Create your environment file
cp .env.example .env.localFill in the values described in the Environment Variables section below.
3. Set up the database
npx prisma migrate deploy
npx prisma generate4. Start the development server
npm run devThe app will be available at http://localhost:3000.
Environment Variables
Authentication (Clerk)
| Variable | Description | Where to get it |
|---|---|---|
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | Public key for the Clerk frontend SDK | Clerk dashboard → API Keys |
CLERK_SECRET_KEY | Server-side Clerk secret | Clerk dashboard → API Keys |
CLERK_WEBHOOK_SECRET | Signing secret for Clerk user lifecycle webhooks | Clerk dashboard → Webhooks |
NEXT_PUBLIC_CLERK_SIGN_IN_URL | Path for the sign-in page | Set to /sign-in |
NEXT_PUBLIC_CLERK_SIGN_UP_URL | Path for the sign-up page | Set to /sign-up |
Database
| Variable | Description | Where to get it |
|---|---|---|
DATABASE_URL | PostgreSQL connection string | Your DB provider (Neon, Supabase, local) |
E2B Sandboxes
| Variable | Description | Where to get it |
|---|---|---|
E2B_API_KEY | API key for provisioning sandboxes | E2B dashboard → API Keys |
E2B_TEMPLATE | Sandbox template name (default: raziel-agents) | E2B dashboard → Templates |
GitHub App
| Variable | Description | Where to get it |
|---|---|---|
GITHUB_APP_ID | GitHub App numeric ID | GitHub → Settings → Developer settings → GitHub Apps |
GITHUB_APP_PRIVATE_KEY | PEM private key for the App (newlines as \n) | GitHub App → Generate a private key |
GITHUB_APP_CLIENT_ID | OAuth Client ID for the App | GitHub App settings |
GITHUB_APP_CLIENT_SECRET | OAuth Client Secret for the App | GitHub App settings |
GITHUB_APP_WEBHOOK_SECRET | HMAC secret for App webhooks | GitHub App settings |
PTY Bridge
| Variable | Description | Where to get it |
|---|---|---|
PTY_BRIDGE_URL | WebSocket URL of the PTY bridge | The pty-bridge service's public domain (e.g. wss://pty.example.com) |
PTY_BRIDGE_SECRET | Shared secret for bridge→API internal calls | Generate with openssl rand -hex 32 |
Encryption
| Variable | Description | Where to get it |
|---|---|---|
ENCRYPTION_KEY | 32-byte hex key for AES-256 encryption of secrets | Generate with openssl rand -hex 32 |
App URL
| Variable | Description | Where to get it |
|---|---|---|
NEXT_PUBLIC_APP_URL | Public base URL of the app | http://localhost:3000 locally; your Vercel URL in production |
Optional: AI Summary
| Variable | Description | Where to get it |
|---|---|---|
ANTHROPIC_API_KEY | Anthropic key used for auto-generating session summaries | console.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 appProduction Deployment
Option A: Docker Compose (Recommended)
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)
- Build the Next.js app:
npm run build - Run the server:
npm start(listens on port 3000 by default) - Deploy the PTY bridge separately (Node.js process or Docker container)
- 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
- Go to GitHub → Settings → Developer settings → GitHub Apps → New GitHub App
- Set Homepage URL to your app's URL
- Set Callback URL to
https://your-app.com/api/github/callback - Set Webhook URL to
https://your-app.com/api/webhooks/github(if using webhooks) - Grant Repository permissions: Contents (Read/Write), Pull requests (Read/Write), Deploy keys (Read/Write), Metadata (Read)
- Generate a private key and download the
.pemfile - 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 passesOn 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