Xeo Forge

The Control Plane for Agentic Work

Agents can act. Xeo Forge makes them accountable.

Xeo Forge is a self-hosted platform for running governed AI agents across software-building and knowledge-work tasks. It combines an approval-first execution engine with persistent context, reusable agent roles, reusable skills, sandboxed workspaces, live event history, and operator controls.

The product is built around one principle:

Give your agent a forge, not a blank check.

What changed in V3

Xeo Forge started as an approval-first coding agent. V3 turns that foundation into a reusable control plane for agentic work without removing the safety contract that made the project different.

Product identity

Xeo Forge is not another terminal wrapper. Claude Code, Codex, and OpenCode are execution surfaces for developers. Manus and Cowork are broader general-purpose agents. Xeo Forge occupies a different layer: it is the place where an organization defines how agents should behave, what they may remember, what they may execute, who must approve them, and how their work is reviewed.

The short version is:

Your agents can execute. Xeo Forge gives execution a policy, a memory, an audit trail, and a proof of work.

V3 product preview

These previews are captured from the running V3 application after authenticating as an operator and configuring the Builder Sentinel profile, Governed Ship Loop skill, Evidence First instruction, and persistent product memory.

Command center	Prompt Studio

Governed run

Product tour

The launch film below is a cinematic product advertisement rather than a UI recording. It expresses the product promise—turning agentic acceleration into visible control—without relying on a live model run or exposing operational error states.

Download the Xeo Forge launch film.

Core workflow

flowchart LR
    A[Describe a goal] --> B[Planning mode]
    B --> C[Read-only inspection]
    C --> D[Structured plan]
    D --> E{Human approval}
    E -- Reject --> B
    E -- Approve --> F[Build mode]
    F --> G[Sandboxed tools]
    G --> H[Preview and verification]
    H --> I[Auditable result]
    I --> J[Optional memory suggestion]
    J --> K{User review}
    K -- Activate --> L[Persistent context]
    K -- Archive --> M[No context change]

Why the control plane matters

Most agent products optimize for autonomy. Xeo Forge optimizes for useful autonomy with a visible boundary. The agent can inspect a codebase, plan a change, edit files, execute verification, and show a preview, but the transition from planning to writing is explicit and persisted.

The same principle applies to memory. Xeo Forge does not silently treat every conversation as permanent training. It extracts bounded memory candidates only after successful work, records their source and confidence, and exposes approval, archive, and delete controls.

Runtime guarantees

• Planning mode cannot write files or execute code, even if the model attempts to call a write tool.
• Approved plans are snapshotted before Build mode and are not silently rewritten during execution.
• Task events use one persisted sequence and one replay path, avoiding divergent in-memory histories.
• File and code access is confined to the task workspace with path checks and command guards.
• Credits are debited atomically and every balance change is recorded in a ledger.
• Model API keys are kept server-side; the application uses one global model configuration.
• Context usage is measured from the live message array and can trigger automatic compaction.
• Memory suggestions are scoped, bounded, source-linked, and reviewable.

Current scope and honest boundaries

V3 is a strong foundation for a governed agent platform, not yet a full replacement for every capability in Manus, Claude Code, Codex, or OpenCode. The current release is strongest at controlled software-building workflows and operator visibility.

The next product layers are intentionally separate from the current core:

1. Persistent Workspaces with members, files, policies, and workspace-level context.
2. First-class modes for Research, Review, Operate, and Build with mode-specific verification contracts.
3. Delegation to specialized agents with explicit budgets and parent-child audit trails.
4. Model routing and connector permissions for browsers, repositories, documents, and external services.
5. Schedules, resumable jobs, richer verification artifacts, and evaluation dashboards.

Windows desktop

Xeo Forge also ships a thin Windows desktop shell for teams that prefer an installable local workspace. The shell starts the production Next.js control plane on loopback, opens it in a hardened Electron window, and supervises local preview or worker processes through the native Go runtime broker.

The desktop build deliberately shares the same product surface as the web app. It does not fork task governance, context compilation, authentication, or persistence into a second implementation.

npm ci
npm run desktop:dev

# Produce an NSIS installer on a Windows CI runner
npm run desktop:build:win

The Windows installer workflow is available under .github/workflows/windows-desktop.yml. A Windows runner is used for the final installer step because Electron Builder requires the Windows signing/packaging toolchain for a native NSIS artifact. The native broker itself is standard-library Go and can be cross-compiled from Linux.

Multi-language architecture

Xeo Forge is intentionally polyglot by boundary, not by fashion. TypeScript remains the control plane because UI, API routes, agent orchestration, context compilation, and product policy benefit from one strict domain model. Go owns the narrow native runtime boundary where a small compiled process supervisor is useful for local workers and previews. SQL remains the persistence contract, and shell scripts are limited to build and packaging automation.

Do not move agent reasoning or approval policy into Go until profiling shows a real bottleneck. The project gains more from explicit boundaries and better observability than from rewriting stable application code.

The first native component is documented in native/runtime-broker, while the Windows lifecycle is documented in desktop/README.md.

Quick start

Local development with SQLite

git clone https://github.com/lahkiri/xeo-forge.git
cd xeo-forge
npm install
cp .env.example .env.local

Set ROOT_ADMIN_EMAIL, ROOT_ADMIN_PASSWORD, and the MODEL_* variables in .env.local, then initialize and run:

npm run db:init
npm run dev

Open http://localhost:3000, sign in as the root admin, and create a planning task. A task starts in read-only Planning mode. Approve its plan before Build mode can write or execute.

Self-hosting with Docker

Xeo Forge includes a production Dockerfile and a Compose stack for PostgreSQL:

cp .env.example .env
docker compose up -d --build

The init service creates the schema, seeds the root admin, and stores the initial global model configuration. The application container starts after initialization succeeds.

Security note: code_execute runs inside the application container. The default container boundary is suitable for semi-trusted workloads, not a hostile multi-tenant threat model. For hostile tenants, use dedicated per-task containers or stronger VM-level isolation.

Development commands

Architecture at a glance

app/                 Next.js pages and API routes
  api/               auth, tasks, context, profiles, skills, admin
lib/
  agent/             runner, loop, tools, prompts, context compiler, preview
  auth/              sessions and route guards
  credits/           atomic debit and ledger operations
  db/                adapter, schema, and the single query writer layer
  sse/               persisted event replay and live delivery
  types.ts           domain types and agent event contracts
native/
  runtime-broker/    Go process supervisor for local native workers
desktop/
  electron/          thin Windows/Linux desktop shell
  native/            generated broker binaries for packaging
docs/
  screenshots/       current V3 product previews
  xeo-forge-v3-vision.md  product and architecture direction
  architecture-and-product-audit.md  product, runtime, and language-boundary audit

Contributing

Keep the approval gate, persisted event ordering, atomic credits, task-scoped authorization, and strict type safety intact. New capabilities should complete the full path from user input to agent behavior, persistence, and UI; a button without an end-to-end route is not a feature.

Before opening a pull request, run:

npm run typecheck
npm test
npm run build
git diff --check

License

MIT. See LICENSE.