# cloudgeni-ai/opengeni architecture

> Architecture diagram of the GitHub repository cloudgeni-ai/opengeni, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cloudgeni-ai/opengeni
- Repository: https://github.com/cloudgeni-ai/opengeni

## Overview

Opengeni is a self-hostable agent service, not an agent model: users start durable sessions through a product surface or API, the service governs access and orchestration, then runs work on managed sandboxes or connected machines while preserving history, approvals, and outputs. The graph emphasizes documented product stages and sampled runtime components. README-level capabilities such as Knowledge and human approvals are retained; unsampled implementation links are dashed where their wiring is not evidenced in the excerpts.

Main entry points: [`apps/api/src/app.ts`](https://github.com/cloudgeni-ai/opengeni/blob/main/apps/api/src/app.ts) (API routes), [`packages/runtime/src/sandbox/routing/routing-session.ts`](https://github.com/cloudgeni-ai/opengeni/blob/main/packages/runtime/src/sandbox/routing/routing-session.ts) (Sandbox routing), [`agent/crates/opengeni-agent/src/engine.rs`](https://github.com/cloudgeni-ai/opengeni/blob/main/agent/crates/opengeni-agent/src/engine.rs) (Agent runner), [`packages/sdk/src/client.ts`](https://github.com/cloudgeni-ai/opengeni/blob/main/packages/sdk/src/client.ts) (SDK client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["Product surfaces"]
  node_web["Web console<br/>[App.tsx]"]
  node_sdk["SDK client<br/>[client.ts]"]
  node_react["Embedded UI<br/>[client.ts]"]
end

subgraph group_service["API and governance"]
  node_api["API routes<br/>[app.ts]"]
  node_mcp["MCP tools<br/>[server.ts]"]
  node_auth["Identity and access"]
  node_integrations["Integrations<br/>[oauth-client.ts]"]
end

subgraph group_sessions["Durable sessions"]
  node_session[("Session state<br/>[database.ts]")]
  node_orchestration["Agent orchestration<br/>[job.rs]"]
  node_agent["Agent runner<br/>[engine.rs]"]
  node_worker["Background workers"]
  node_approvals["Human approvals<br/>[server.ts]"]
end

subgraph group_execution["Compute and tools"]
  node_sandbox["Sandbox routing<br/>[routing-session.ts]"]
  node_machine["Connected machine<br/>[browser_bridge.rs]"]
  node_browser["Browser control<br/>[server.ts]"]
  node_relay["Live relay<br/>[server.rs]"]
end

subgraph group_outputs["Knowledge and outputs"]
  node_knowledge["Agent Knowledge<br/>[knowledge.ts]"]
  node_artifacts["Artifacts<br/>[service.ts]"]
  node_objectstore[("Object storage")]
end

node_human(("User"))
node_external{{"Model providers"}}

node_human -->|"starts work"| node_web
node_human -->|"starts work"| node_sdk
node_web -.->|"submits session"| node_api
node_react -->|"uses client"| node_sdk
node_sdk -.->|"calls API"| node_api
node_api -.->|"checks identity"| node_auth
node_api -.->|"routes tools"| node_mcp
node_mcp -->|"reads and updates"| node_session
node_api -.->|"handles OAuth"| node_integrations
node_api -.->|"persists events"| node_session
node_session -.->|"drives turns"| node_orchestration
node_orchestration -.->|"starts jobs"| node_agent
node_agent -.->|"executes work"| node_sandbox
node_sandbox -.->|"dispatches work"| node_machine
node_sandbox -.->|"invokes models"| node_external
node_sandbox -.->|"controls browser"| node_browser
node_agent -.->|"streams events"| node_relay
node_api -.->|"gates risky actions"| node_approvals
node_api -.->|"serves retrieval"| node_knowledge
node_api -.->|"manages artifacts"| node_artifacts
node_worker -->|"reads objects"| node_objectstore
node_artifacts -.->|"stores content"| node_objectstore

click node_web "https://github.com/cloudgeni-ai/opengeni/blob/main/apps/web/src/App.tsx"
click node_sdk "https://github.com/cloudgeni-ai/opengeni/blob/main/packages/sdk/src/client.ts"
click node_react "https://github.com/cloudgeni-ai/opengeni/blob/main/packages/react/src/client.ts"
click node_api "https://github.com/cloudgeni-ai/opengeni/blob/main/apps/api/src/app.ts"
click node_mcp "https://github.com/cloudgeni-ai/opengeni/blob/main/apps/api/src/mcp/server.ts"
click node_auth "https://github.com/cloudgeni-ai/opengeni/blob/main/apps/api/src/auth/managed-auth-session-adapter.ts"
click node_integrations "https://github.com/cloudgeni-ai/opengeni/blob/main/apps/api/src/integrations/oauth-client.ts"
click node_session "https://github.com/cloudgeni-ai/opengeni/blob/main/packages/db/src/database.ts"
click node_orchestration "https://github.com/cloudgeni-ai/opengeni/blob/main/agent/crates/opengeni-agent/src/job.rs"
click node_agent "https://github.com/cloudgeni-ai/opengeni/blob/main/agent/crates/opengeni-agent/src/engine.rs"
click node_sandbox "https://github.com/cloudgeni-ai/opengeni/blob/main/packages/runtime/src/sandbox/routing/routing-session.ts"
click node_machine "https://github.com/cloudgeni-ai/opengeni/blob/main/agent/crates/opengeni-agent/src/browser_bridge.rs"
click node_browser "https://github.com/cloudgeni-ai/opengeni/blob/main/packages/browserd/src/server.ts"
click node_relay "https://github.com/cloudgeni-ai/opengeni/blob/main/agent/crates/opengeni-relay/src/server.rs"
click node_knowledge "https://github.com/cloudgeni-ai/opengeni/blob/main/apps/api/src/routes/knowledge.ts"
click node_artifacts "https://github.com/cloudgeni-ai/opengeni/blob/main/packages/core/src/domain/editable-artifacts/service.ts"
click node_objectstore "https://github.com/cloudgeni-ai/opengeni/blob/main/packages/storage/src/object-storage-bounded.ts"
click node_worker "https://github.com/cloudgeni-ai/opengeni/blob/main/apps/worker/src/editable-artifact-materializer-storage.ts"
click node_approvals "https://github.com/cloudgeni-ai/opengeni/blob/main/apps/api/src/mcp/server.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_sdk,node_react,node_human toneBlue
class node_api,node_mcp,node_auth,node_integrations toneAmber
class node_session,node_orchestration,node_agent,node_worker,node_approvals toneMint
class node_sandbox,node_machine,node_browser,node_relay toneRose
class node_knowledge,node_artifacts,node_objectstore,node_external toneIndigo
```

## Components

### Product surfaces

- [Web console](https://github.com/cloudgeni-ai/opengeni/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [SDK client](https://github.com/cloudgeni-ai/opengeni/blob/main/packages/sdk/src/client.ts): `packages/sdk/src/client.ts`
- [Embedded UI](https://github.com/cloudgeni-ai/opengeni/blob/main/packages/react/src/client.ts): `packages/react/src/client.ts`

### API and governance

- [API routes](https://github.com/cloudgeni-ai/opengeni/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [MCP tools](https://github.com/cloudgeni-ai/opengeni/blob/main/apps/api/src/mcp/server.ts): `apps/api/src/mcp/server.ts`
- [Identity and access](https://github.com/cloudgeni-ai/opengeni/blob/main/apps/api/src/auth/managed-auth-session-adapter.ts): `apps/api/src/auth/managed-auth-session-adapter.ts`
- [Integrations](https://github.com/cloudgeni-ai/opengeni/blob/main/apps/api/src/integrations/oauth-client.ts): `apps/api/src/integrations/oauth-client.ts`

### Durable sessions

- [Session state](https://github.com/cloudgeni-ai/opengeni/blob/main/packages/db/src/database.ts): `packages/db/src/database.ts`
- [Agent orchestration](https://github.com/cloudgeni-ai/opengeni/blob/main/agent/crates/opengeni-agent/src/job.rs): `agent/crates/opengeni-agent/src/job.rs`
- [Agent runner](https://github.com/cloudgeni-ai/opengeni/blob/main/agent/crates/opengeni-agent/src/engine.rs): `agent/crates/opengeni-agent/src/engine.rs`
- [Background workers](https://github.com/cloudgeni-ai/opengeni/blob/main/apps/worker/src/editable-artifact-materializer-storage.ts): `apps/worker/src/editable-artifact-materializer-storage.ts`
- [Human approvals](https://github.com/cloudgeni-ai/opengeni/blob/main/apps/api/src/mcp/server.ts): `apps/api/src/mcp/server.ts`

### Compute and tools

- [Sandbox routing](https://github.com/cloudgeni-ai/opengeni/blob/main/packages/runtime/src/sandbox/routing/routing-session.ts): `packages/runtime/src/sandbox/routing/routing-session.ts`
- [Connected machine](https://github.com/cloudgeni-ai/opengeni/blob/main/agent/crates/opengeni-agent/src/browser_bridge.rs): `agent/crates/opengeni-agent/src/browser_bridge.rs`
- [Browser control](https://github.com/cloudgeni-ai/opengeni/blob/main/packages/browserd/src/server.ts): `packages/browserd/src/server.ts`
- [Live relay](https://github.com/cloudgeni-ai/opengeni/blob/main/agent/crates/opengeni-relay/src/server.rs): `agent/crates/opengeni-relay/src/server.rs`

### Knowledge and outputs

- [Agent Knowledge](https://github.com/cloudgeni-ai/opengeni/blob/main/apps/api/src/routes/knowledge.ts): `apps/api/src/routes/knowledge.ts`
- [Artifacts](https://github.com/cloudgeni-ai/opengeni/blob/main/packages/core/src/domain/editable-artifacts/service.ts): `packages/core/src/domain/editable-artifacts/service.ts`
- [Object storage](https://github.com/cloudgeni-ai/opengeni/blob/main/packages/storage/src/object-storage-bounded.ts): `packages/storage/src/object-storage-bounded.ts`

### Other components

- **User**
- **Model providers**

## Connections

- User → Web console: starts work (evidence: `README.md`)
- User → SDK client: starts work (evidence: `README.md`)
- Web console → API routes: submits session
- Embedded UI → SDK client: uses client (evidence: `packages/react/src/client.ts`)
- SDK client → API routes: calls API
- API routes → Identity and access: checks identity (evidence: `apps/api/src/app.ts`)
- API routes → MCP tools: routes tools
- MCP tools → Session state: reads and updates (evidence: `apps/api/src/mcp/server.ts`)
- API routes → Integrations: handles OAuth
- API routes → Session state: persists events (evidence: `README.md`)
- Session state → Agent orchestration: drives turns
- Agent orchestration → Agent runner: starts jobs (evidence: `agent/crates/opengeni-agent/src/engine.rs`)
- Agent runner → Sandbox routing: executes work
- Sandbox routing → Connected machine: dispatches work
- Sandbox routing → Model providers: invokes models (evidence: `README.md`)
- Sandbox routing → Browser control: controls browser
- Agent runner → Live relay: streams events
- API routes → Human approvals: gates risky actions (evidence: `README.md`)
- API routes → Agent Knowledge: serves retrieval (evidence: `README.md`)
- API routes → Artifacts: manages artifacts
- Background workers → Object storage: reads objects (evidence: `apps/worker/src/editable-artifact-materializer-storage.ts`)
- Artifacts → Object storage: stores content
