Architecture

How It Works

Three pieces. Worth understanding before you trust anything with your code.

flamel.dev — auth only

flamel.dev handles identity and nothing else. When you sign in, it issues a short-lived RS256 JWT. Your server fetches the public JWKS once, caches it, and validates tokens offline from there.

flamel.dev never sees your prompts, your code, or anything that happens in a session. The only data it holds is your account email and the list of server IDs you've registered.

flamel_server — everything else

A Rust/Axum binary running on your machine. It manages sessions, stores history in SQLite, runs the MCP servers, and spawns supported provider CLIs such as claude and codex. web.flamel.dev connects directly to this — no proxy, no relay.

Provider subprocess

Each session spawns the selected provider process, such as claude or codex, with the runtime arguments that provider needs for streaming output. The server streams normalized events to your browser over SSE. When the session ends, the process is killed.

Every session runs inside a bubblewrap sandbox — an isolated Linux user namespace with restricted filesystem access. That's why --privileged is required on the Docker container.

web.flamel.dev

A static React SPA. It connects to whatever server URL you registered — traffic goes browser → your server directly. flamel.dev is not in the path.

Architecture

Browser (web.flamel.dev)
  │  HTTP + SSE → your server, directly
  ▼
flamel_server :8181
  ├── auth ─────── validates JWT (JWKS cached, fully offline)
  ├── sessions ─── provider subprocess × N  (bubblewrap sandbox)
  ├── MCP ──────── flamel_mcp, git_mcp, docs_mcp, …
  └── SQLite ────── /data/flamel.db