RAZIEL.docs

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 (tabIndex routing)
  • Verifies the caller's Clerk token via /api/internal/pty-verify before 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 ProjectBuild captures 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 workBranch

Data 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
StatusMeaning
startingSandbox being provisioned
runningSandbox live, agent may be active
pausedSandbox snapshotted (resumable)
stoppedUser terminated session; sandbox killed
completedAgent exited cleanly (exit code 0)
failedAgent exited with error
errorSandbox no longer resumable or infrastructure error
Architecture · Raziel