Architecture
How Raziel works under the hood — data flow, component breakdown, security model, and session lifecycle.
Overview
Raziel is a web-based AI coding platform. When a user starts a session, a fresh isolated sandbox is provisioned in the cloud, a repository is cloned into it, and an AI agent CLI is launched on first terminal attach. All code edits happen inside that sandbox; work is pushed to a dedicated branch on GitHub when the user is ready.
Browser (Next.js)
|
| HTTPS (Clerk session token)
v
Vercel Edge / Serverless (Next.js API routes)
| |
| Sandbox SDK | PostgreSQL (Prisma)
v v
Cloud Sandbox Neon / Supabase DB
(Ubuntu sandbox) (sessions, projects,
/workspace (git) secrets, builds)
|
| WebSocket (PTY)
v
PTY Bridge
(pty-bridge/)
|
| agent CLI stdin/stdout
v
claude / codex / opencode
(runs inside the sandbox)Component Breakdown
Web App (Vercel / Next.js)
The primary user interface and API surface. Built with Next.js App Router and deployed to Vercel.
- Pages: dashboard, session terminal, project settings, analytics, prompt library
- API routes (
app/api/): session CRUD, project CRUD, push/diff/fork, webhooks, budget, search - Auth: every request is authenticated via a Clerk session token resolved by
getScope() - Database: Prisma ORM against PostgreSQL (session records, projects, secrets, builds, webhooks)
PTY Bridge
Serverless functions cannot hold a long-lived WebSocket open, so the interactive terminal lives on a separate long-running service (pty-bridge/, the pty-bridge service in docker-compose.yml).
- Accepts browser WebSocket connections and proxies them to the cloud sandbox PTY
- Bumps the sandbox TTL on attach so an active session does not expire mid-use
- Tees chat events to the database (persisted transcript for replay on reconnect)
- Handles multi-tab terminal sessions (
tabIndexrouting) - Verifies the caller's Clerk token via
/api/internal/pty-verifybefore opening a PTY
Preview Proxy
A lightweight proxy that forwards HTTP traffic from the browser to a port running inside the sandbox (e.g. localhost:3000 in the agent's dev server). Enables live previews without exposing the sandbox to the public internet.
Sandboxes
Fully managed, isolated cloud sandboxes. Each session gets its own sandbox.
- Template:
raziel-agents(Ubuntu image pre-installed with Claude Code, Codex, opencode, and mise) - Workspace:
/workspace— the git working tree; all agent edits happen here - Timeout: 1 hour default (Hobby), up to 24 hours (Pro). The PTY bridge extends TTL on attach
- Pause/resume: sandboxes can be paused (snapshot fs+memory, no TTL) and resumed later
- Snapshots: a
ProjectBuildcaptures a fully-built sandbox image; new sessions boot from it instantly, skipping the clone + install step
Data Flow: Session Start
1. Browser POST /api/sessions
|
v
2. API route resolves scope (Clerk userId / orgId)
Checks monthly budget ceiling
Resolves project repos + deploy keys
Computes workBranch name (raziel/<user>/<slug>-<id>)
|
v
3. createAgentSandbox() (lib/e2b.ts)
- Sandbox.create("raziel-agents") or Sandbox.create(snapshotId)
- Batched file writes: agent auth, AGENTS.md context, MCP config, deploy key, skills
- Single shell run: mkdir + chmod + git config + SSH remote + snapshot self-heal
- cloneRepo(): SSH (deploy key) or HTTPS-then-scrub; cuts workBranch
|
v
4. DB: AgentSession created (status: "running")
Webhook fired: session.started
|
v
5. Browser opens WebSocket to PTY bridge
Bridge verifies token → connects to sandbox PTY
Bridge sends agentStartCommand() to PTY stdin
|
v
6. Agent CLI starts inside sandbox
Reads ~/.raziel/context.md as system context
Works in /workspace on workBranchData Flow: Push to GitHub
Browser POST /api/sessions/:id/push
|
v
API route connects to sandbox (Sandbox.connect)
Runs git script inside sandbox:
git add -A
git checkout -B <workBranch>
git commit -m "<message>"
git push origin <workBranch> --force-with-lease
|
v (uses deploy key already on disk in sandbox)
GitHub receives push
|
v
API route calls GitHub REST API (server-side, OAuth token)
Opens pull request: workBranch → baseBranch
|
v
DB: session.prUrl + prNumber updated
Response: { branch, pushed, prUrl, prNumber, headSha }Security Model
Per-Session Isolation
Every session runs in its own managed cloud sandbox. Sandboxes cannot communicate with each other. Filesystem, network, and process namespaces are isolated.
Deploy Keys (Not OAuth Tokens)
Git push inside the sandbox uses a per-repo Ed25519 deploy key rather than the user's OAuth token:
- The public key is registered with GitHub as a deploy key (read/write, repo-scoped)
- The private key is AES-encrypted at rest in
ProjectDeployKey - At session start it is written to
~/.ssh/id_ed25519(mode 0600) inside the sandbox - The clone URL is immediately rewritten to the plain HTTPS URL after token clone so no credential persists in
.git/config
Token Scrubbing
If a deploy key is unavailable, clone falls back to HTTPS with a transient token. After clone, the remote URL is immediately reset to the plain HTTPS URL via git remote set-url. The token never persists in .git/config.
Credential Footprint Minimisation
Only the selected agent's credentials are written into the sandbox. For example, if the user starts a Claude Code session, only ANTHROPIC_API_KEY enters the sandbox — not the OpenAI key. Files holding plaintext secrets are chmod 0600; dirs are 0700.
API Authentication
All API endpoints resolve a Clerk session token via getScope(). Unauthenticated requests receive 401. Every database query is scoped to { userId, orgId } — users cannot read or modify another scope's data.
Budget Enforcement
Session creation checks the user's monthlyBudgetUsd against the current month's estimatedCostUsd sum. When the budget is exceeded, session creation returns 402 Payment Required.
Session Lifecycle
create → clone/snapshot → PTY attach → agent runs → push → complete
| | | | | |
DB: running repo in agent CLI edits in PR on DB: stopped
/workspace launched /workspace GitHub stoppedAt set
AI summary
generated
webhook fired| Status | Meaning |
|---|---|
starting | Sandbox being provisioned |
running | Sandbox live, agent may be active |
paused | Sandbox snapshotted (resumable) |
stopped | User terminated session; sandbox killed |
completed | Agent exited cleanly (exit code 0) |
failed | Agent exited with error |
error | Sandbox no longer resumable or infrastructure error |