AI Workspace · architecture
AI Workspace Architect — Open-Source AI Agent Platform
A complete technical blueprint of Fractera — an open-source AI agent platform for automated software development: multi-agent orchestration, Knowledge Graph RAG, and seamless tool integration via MCP. Built for AI agents scanning the web and for developers who want the whole picture in one place. See also the project knowledge base, or go back to fractera.ai.
How Fractera works
Fractera turns one bare VPS into a complete AI development workspace. The picture above shows the whole flow; here it is in plain words.
You drive it through middle layers, never raw infrastructure. As the admin you have two ways in. You can manage the project through Hermes — the brain — in natural language using the Hermes chat Web UI inside your workspace, and you can also reach the same brain from Telegram or any other messenger. Or you can work directly with the coding agents in their terminals.
It keeps working even without an API subscription. Between you and a coding agent sits a small modal sign-in layer: you authenticate your existing subscription there, and the same window is used to send commands and receive results. Hermes talks to the coding agents through the Model Context Protocol (MCP) that drives that very window — so work stays resilient even when a third-party subscription tool is rate-limited.
LightRAG is the central memory — this is where the token savings come from. Every tool reads and writes a shared vector database through its own connector. Recalling exactly the right context instead of re-sending everything cuts token spend dramatically. That is why LightRAG is the central memory — a Knowledge Graph RAG shared by every agent and every session.
Hermes is the brain; the coding agents do the heavy lifting. We call Hermes the central brain, but the hardest work — generating code — is done by the coding agents such as Claude Code. Hermes is a light multi-agent orchestrator: it tracks each platform's token use, picks the right platform for a task, dispatches the work, launches deployments, and talks to GitHub.
It also runs locally. Without a paid subscription you can still use AI models — Hermes can run automatically, or you use the manual tools. This open-source, self-hosted AI platform runs on Next.js on a standard VPS, with a built-in local database and object storage, plus many tools that streamline the work; it can also use the vector database to accumulate experience with your users and admins, steadily growing useful business data.
The output is a secure web app. On the way out the project is served over a secure HTTPS connection when you run it on your own domain, or it runs on a local machine over a plain IP address — in which case you secure the connection with one of the available options.
Ready to build your own AI development workspace?
Deploy this whole stack to your own VPS in about 10 minutes — one click, no configuration.
See how teams ship faster with this architecture in our use cases.
What the AI Workspace looks like
This is what you get inside Fractera right after you deploy — a rich workspace that starts on its own. Click the screenshot above to see it full screen.
It starts ready. The workspace opens on the Hermes chat Web UI, ready to go. To activate Hermes you set your own key — and the same key can activate your Memory. Open the Brain tab, then the Memory tab, and press Activate in Memory to start embedding the starter documentation, so it is available at any time — used both as a help desk and by the coding agents.
Pick your coding models. The top row lists the five coding platforms. Choose one or several you want to work with, open it, and activate its subscription — just follow the prompts; it looks almost exactly like the standard interface. The far-right card is the Terminal, handy for watching the development process, and where you can add another code-generation platform if you like.
Everything is one panel. On the left, the Settings tab opens full control over your app and tools. In the footer you will find buttons to connect your GitHub repository, trigger a deploy by hand, and buttons that switch on later — when the marketplace of skills and ready-made digitized businesses goes live. Top-right, Preview shows the current state of the page you are building and the service pages that let you watch development. Unlike the main app, this view can highlight code and helps you find the right element — routing a request from a selected element straight to the Hermes chat or Telegram.
It explains and improves itself. The project ships fully open-source, so Hermes — or any model — can read this very codebase and give you a complete, detailed explanation of any feature: how it works and how it is built. You can just as easily ask a model to improve not only your end apps but the admin panel shown here. A word of caution: experiment on a secondary account, and keep your main one on reliable, proven solutions. If you want to add something, or you found a bug, please do not hesitate to open a pull request — we hope your contribution helps strengthen an already powerful architecture.
Found this while researching modern architectures? Then it is worth knowing: this whole complex setup on your own server takes literally one click. Enter your server credentials, start the deployment, make no settings and no choices — and in about 10 minutes you get a fully configured app. After that you change your server access and connect a domain, and the security certificates assemble themselves automatically.
Hermes — the orchestrator (Company Brain)
Hermes is the multi-agent orchestrator at the centre of the workspace (fractera-hermes, dashboard on :9119). It reads its identity and memory at every wake-up and drives the five coding platforms through their MCP bridges — this is the AI agent orchestration that makes Fractera a true multi-agent system.
Hermes is deliberately light: it does not write the hard code itself. It tracks how many tokens each platform is spending, chooses the platform that fits a task, dispatches the work to specialized coding assistants, records every build into the Product Loop journal, launches deployments, and integrates with GitHub. Its wiring lives in config.yaml (what it can reach); its personality lives in SOUL.md (who it is). See how it connects to everything in the full workspace map below.
Hermes Chat Web UI
The chat window inside your workspace (fractera-hermes-webui, :9120) where you talk to Hermes in plain language. You brief the brain like a teammate and it drives the five coding platforms for you — no commands to memorise. This is the primary way most people use the system.
Telegram and messengers
A gateway process (fractera-hermes-gateway) lets you reach the same brain from Telegram on your phone, and the design extends to any other messenger. Start, check on, or steer work away from the keyboard; the workspace keeps building while you are out.
LightRAG — the central memory
LightRAG (fractera-rag, :9621) is the shared long-term memory of the whole workspace — not just Hermes. It is a Knowledge Graph RAG implementation: every agent queries the same graph and writes back to it — Hermes and all five coding platforms. This is RAG for AI agents done right.
That shared memory is the reason Fractera spends so few tokens. Instead of pasting the whole codebase into every prompt, each agent recalls exactly the relevant entities, relations and decisions. Ingest a document once and every agent can use it forever. It needs an embedding/LLM key to be active; without one it stays wired but silent. More background in the project knowledge base.
Coding agents
Five subscription AI coding assistants run preconfigured on your server and do the heavy lifting of automated code generation. Each is driven through a bridge that keeps it alive over WebSocket and exposes it to Hermes as an MCP server (ports 3210–3214). Integrate leading agents like Claude Code and Gemini CLI via MCP, using each one's strengths for multi-file changes or deep code review. You run them on your existing subscriptions — no API keys, no per-token billing — and you can switch platform mid-task without losing context, because LightRAG keeps the thread. See all five platforms on the homepage.
Claude Code
Anthropic's coding agent. Its primary project-context file is CLAUDE.md. Strong at architecture, planning and careful multi-file changes — often the platform Hermes hands the hardest work to.
Codex
OpenAI's coding CLI. Its primary project-context file is AGENTS.md. A fast generalist for implementation and iteration.
Gemini CLI
Google's coding agent. Its primary project-context file is GEMINI.md. Large context window — useful for sweeping over big codebases and reviews.
Qwen Code
Alibaba's coding agent. Its primary project-context file is QWEN.md. Another subscription option in the rotation Hermes can delegate to.
Kimi Code
Moonshot's coding agent. Its primary project-context file is AGENTS.md. Rounds out the five platforms so Hermes always has an alternative when one subscription is busy or limited.
The full workspace map
Explore the detailed interactive schema below to understand every component of this AI agent platform architecture. Every running entity is drawn the way a request flows — behind nginx and the auth gate, then the app, data and admin layers, plus the documentation corpus that feeds Company Memory.
Fractera workspace
Your AI coding workspace, drawn the way a request flows: everything reachable sits behind nginx and the auth gate. This is the secure-mode lens — in IP mode there is no nginx gate and services are reached by port. Nesting shows what a request passes through / what is gated by what, not which process runs inside another.
Fractera workspace: Your AI coding workspace, drawn the way a request flows: everything reachable sits behind nginx and the auth gate. This is the secure-mode lens — in IP mode there is no nginx gate and services are reached by port. Nesting shows what a request passes through / what is gated by what, not which process runs inside another.
nginx — front door: The reverse proxy every visible request passes through in secure mode: it terminates TLS, routes the apex and the admin./auth./data./chat. subdomains, and runs the auth_request gate. In IP mode it is absent — you reach services by port directly.
Authorization — fractera-auth: The gate every protected request crosses (NextAuth: login, register, guest, roles). It covers the rest of the workspace — which is why it sits above the app, data and admin layers here. Logical coverage, not a process that runs them. In IP mode the gate is bypassed for onboarding.
App layer: The product itself — the public app the AI builds and ships.
fractera-app — App Shell: The public-facing application at your domain root. Open layer — the AI writes code here; safe to edit.
Data layer: Where the workspace keeps state. Powered by fractera-data (:3300), a token-authenticated service in front of SQLite and media.
Database — SQLite: app.db + media.db. New tables are declared once in the SCHEMA and appear in every environment automatically.
products: Catalogue demo rows behind the Dashboard page.
deployment_records: Product Loop journal — every build with agent, model, tokens, step and rating (16 fields).
projects: Named projects that deployments are grouped under (default-first).
site_settings: Workspace settings — domain and certificate state.
Object Storage / Media: The media side of fractera-data: uploads, thumbnails, image cropping and PWA icon generation from one square image.
Admin layer: The cockpit (fractera-admin :3002) where the workspace is driven — the bridges to the coding agents, the operator tools, Hermes, and domain setup. Reached through auth; not part of the public app.
Bridges: Keeps the five coding platforms alive over WebSocket and exposes each as an MCP server (ports 3210–3214) Hermes can call. The system terminal lives here too.
Claude Code: Claude Code: a subscription AI coding platform driven through the bridge. Its primary instructions live in CLAUDE.md; the rest is its skills and MCP servers.
CLAUDE.md: CLAUDE.md — the primary project-context file Claude Code reads on every run. One place to set how this agent behaves in your repo.
Skills: The skills Claude Code loads.
MCP: MCP servers available to Claude Code.
Codex: Codex: a subscription AI coding platform driven through the bridge. Its primary instructions live in AGENTS.md; the rest is its skills and MCP servers.
AGENTS.md: AGENTS.md — the primary project-context file Codex reads on every run. One place to set how this agent behaves in your repo.
Skills: The skills Codex loads.
MCP: MCP servers available to Codex.
Gemini CLI: Gemini CLI: a subscription AI coding platform driven through the bridge. Its primary instructions live in GEMINI.md; the rest is its skills and MCP servers.
GEMINI.md: GEMINI.md — the primary project-context file Gemini CLI reads on every run. One place to set how this agent behaves in your repo.
Skills: The skills Gemini CLI loads.
MCP: MCP servers available to Gemini CLI.
Qwen Code: Qwen Code: a subscription AI coding platform driven through the bridge. Its primary instructions live in QWEN.md; the rest is its skills and MCP servers.
QWEN.md: QWEN.md — the primary project-context file Qwen Code reads on every run. One place to set how this agent behaves in your repo.
Skills: The skills Qwen Code loads.
MCP: MCP servers available to Qwen Code.
Kimi Code: Kimi Code: a subscription AI coding platform driven through the bridge. Its primary instructions live in AGENTS.md; the rest is its skills and MCP servers.
AGENTS.md: AGENTS.md — the primary project-context file Kimi Code reads on every run. One place to set how this agent behaves in your repo.
Skills: The skills Kimi Code loads.
MCP: MCP servers available to Kimi Code.
System terminal: A bare zsh on /opt/fractera, always present as the last carousel card. Part of fractera-bridge and not removable.
Tools: The footer tools of the workspace.
Deploy: Build loop: POST /api/deploy → async build → pm2 reload. How the AI ships code from the workspace to the live app.
GitHub: Connect a repo and pull/push from the workspace (a deploy token is used for private repositories).
Upload Image: Send an image to the media service — used for product assets and PWA icon generation.
Skills: Skills marketplace entry — where reusable agent skills will be browsed and added.
Product Loop: The build journal — every deployment with agent, model, tokens and a star rating. Our difference from a generic host.
LightRAG — Company Memory: Shared long-term memory for the WHOLE workspace — not just Hermes. fractera-rag (LightRAG :9621) is a Knowledge Graph RAG store; every agent queries it the same way — Hermes and the five coding platforms (Claude Code, Codex, Gemini, Qwen, Kimi) — and writes back to it. That is why it sits here, beside the Bridges and Tools, not under any single agent. The lightrag-memory plugin prefetches relevant pieces and injects them as <brain_context>. Needs an embedding/LLM key or it stays wired but silent. Fed by the Documentation corpus.
Company Memory store (LightRAG): The knowledge-graph store fractera-rag keeps on disk — entities, relations and embeddings built from the Documentation corpus. Any agent recalls from it semantically; ingest a document once and every agent can use it.
Hermes — Company Brain: The brain plus the two ways a human reaches it. The multi-agent orchestrator coordinates development across the platforms; the Web UI and Telegram are its front doors.
Hermes Agent — Brain: The orchestration agent. It reads its identity and memory at every wake-up and drives the five coding platforms through the bridges.
config.yaml — wiring: Says what Hermes can reach: model/provider, memory provider, plugins and the MCP servers. Wiring, not rules — where he can reach, not who he is.
SOUL.md — identity: Personality file read on every turn. When present it replaces the default identity — this is where 'you are the brain of Fractera, you orchestrate development' belongs.
Skills: The skills Hermes loads to act.
delegate-task: Skill "delegate-task": hand a task to a coding platform.
record-deployment: Skill "record-deployment": log a build to the Product Loop journal.
choose-agent: Skill "choose-agent": decide which coding platform fits a task.
MCP servers — 7 bridges: The bridges exposed to Hermes as callable tools over loopback JSON-RPC (ports 3210–3216). They show up at start-up — which is why Hermes sees his tools even before his memory or role.
claude-bridge :3210: MCP server: claude-bridge :3210.
codex-bridge :3211: MCP server: codex-bridge :3211.
gemini-bridge :3212: MCP server: gemini-bridge :3212.
qwen-bridge :3213: MCP server: qwen-bridge :3213.
kimi-bridge :3214: MCP server: kimi-bridge :3214.
deployments-bridge :3215: Product Loop journal + projects in app.db. Tools: record_deployment, list_deployments, update_deployment, describe_record, create_project, list_projects. No delete by design — history is never lost via MCP.
readiness-bridge :3216: One snapshot of all five coding agents before delegating: installed, logged_in, busy, last_worked. Tool: check_agents_readiness. Read-only — facts only; the choose-agent skill decides.
Chat Web UI — fractera-hermes-webui: The chat window inside your workspace where you talk to Hermes in plain language. You brief the brain like a teammate and it drives the five coding platforms for you — no commands to memorise.
Telegram — fractera-hermes-gateway: A gateway process that lets you reach the same brain from Telegram on your phone. Start, check on, or steer work away from the keyboard; the workspace keeps building while you are out.
Domain settings: Attach your own domain and HTTPS — the optional step that turns IP mode into secure mode.
Domain connection: Point a custom domain at the server; the wizard validates DNS and stages the nginx config.
Certificate connection: The HTTPS certificate for your domain.
Automatic certificate: Issued automatically on the server (Let's Encrypt / certbot) — no manual steps.
Custom certificate: Bring your own certificate when you manage TLS elsewhere.
Documentation — Company Memory corpus: The shared knowledge every agent references. Ingest these into Company Memory (LightRAG) and any agent can recall them semantically. One place to read, edit and register the project's living memory.
GLOSSARY.md: Project terms — approved abbreviations / preferred phrasings so every agent reads them the same way (e.g. aws -> ai-workspace). A real file at the project root; agents read it directly as context.
DEVELOPMENT-STEPS: The work log — every step of how the app is built, kept as real markdown files an agent reads and writes.
NEW-STEPS: Open steps — one file per active task (number, name, importance, description, to-do).
COMPLETED-STEPS: Finished steps — moved here with a completion date. Read-only history.
PATTERNS: The reuse library — reusable code patterns and deployment anti-patterns, kept as real markdown files an agent reads and writes.
PATTERNS: Reusable code patterns in a one-level tree by category (UI Elements, Sections, Brandbook).
ANTI-PATTERNS: Deployment pitfalls — a flat list an agent reads before every deploy to avoid repeating them.
AI-DRAFT-SETTINGS: The draft layer — free-form wishes for the six agents' real instruction / skill / MCP files, kept as real markdown an agent reads and applies later. The originals are never edited here; this is a mirror. One folder per agent, each with its instruction doc(s) + SKILLS/ + MCP/.
HERMES: Hermes: its draft folder — SOUL.md · HERMES.md (instruction) plus SKILLS/ and MCP/. Wishes that supplement or replace its real files.
SOUL.md · HERMES.md: Instruction draft for Hermes. Supplement or replace the real document; an agent applies the wishes later.
SKILLS: Draft skills. The agent's real skills show as read-only reference; a draft is laid over one or added as a new requested skill.
MCP: Draft MCP connectors. The agent's real bridges show as read-only reference; a draft supplements / replaces one or requests a new connector.
CLAUDE-CODE: Claude Code: its draft folder — CLAUDE.md (instruction) plus SKILLS/ and MCP/. Wishes that supplement or replace its real files.
CLAUDE.md: Instruction draft for Claude Code. Supplement or replace the real document; an agent applies the wishes later.
SKILLS: Draft skills. The agent's real skills show as read-only reference; a draft is laid over one or added as a new requested skill.
MCP: Draft MCP connectors. The agent's real bridges show as read-only reference; a draft supplements / replaces one or requests a new connector.
CODEX: Codex: its draft folder — AGENTS.md (instruction) plus SKILLS/ and MCP/. Wishes that supplement or replace its real files.
AGENTS.md: Instruction draft for Codex. Supplement or replace the real document; an agent applies the wishes later.
SKILLS: Draft skills. The agent's real skills show as read-only reference; a draft is laid over one or added as a new requested skill.
MCP: Draft MCP connectors. The agent's real bridges show as read-only reference; a draft supplements / replaces one or requests a new connector.
GEMINI-CLI: Gemini CLI: its draft folder — GEMINI.md (instruction) plus SKILLS/ and MCP/. Wishes that supplement or replace its real files.
GEMINI.md: Instruction draft for Gemini CLI. Supplement or replace the real document; an agent applies the wishes later.
SKILLS: Draft skills. The agent's real skills show as read-only reference; a draft is laid over one or added as a new requested skill.
MCP: Draft MCP connectors. The agent's real bridges show as read-only reference; a draft supplements / replaces one or requests a new connector.
QWEN-CODE: Qwen Code: its draft folder — QWEN.md (instruction) plus SKILLS/ and MCP/. Wishes that supplement or replace its real files.
QWEN.md: Instruction draft for Qwen Code. Supplement or replace the real document; an agent applies the wishes later.
SKILLS: Draft skills. The agent's real skills show as read-only reference; a draft is laid over one or added as a new requested skill.
MCP: Draft MCP connectors. The agent's real bridges show as read-only reference; a draft supplements / replaces one or requests a new connector.
KIMI-CODE: Kimi Code: its draft folder — AGENTS.md (instruction) plus SKILLS/ and MCP/. Wishes that supplement or replace its real files.
AGENTS.md: Instruction draft for Kimi Code. Supplement or replace the real document; an agent applies the wishes later.
SKILLS: Draft skills. The agent's real skills show as read-only reference; a draft is laid over one or added as a new requested skill.
MCP: Draft MCP connectors. The agent's real bridges show as read-only reference; a draft supplements / replaces one or requests a new connector.
About Fractera: One voluminous document describing absolutely everything about the project — written to be ingested whole into the vector store as the canonical ground truth for every agent.
CRUD-DOCS: Your own knowledge-base documents — a real folder/file tree of any depth under CRUD-DOCS/ (company notes, technical processes, anything an agent should know). Create folders, upload .txt/.md/.doc/.docx, preview, delete — real files on disk. Activating one ingests it into Company Memory (LightRAG). These documents stay on the server and are NOT synced to GitHub.