# nightly-labs/openbot architecture

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

- Interactive diagram: https://gitdiagram.com/nightly-labs/openbot
- Repository: https://github.com/nightly-labs/openbot

## Overview

OpenBot is a local-first workspace for persistent AI teammates, delivered as a desktop app with mobile and joined-server access. Its main workflow is creating an agent, running provider-backed conversations in independent workspaces, and coordinating work through queues, shared channels, messaging, and file transfers. The graph also preserves the embedded browser, account services, and hosted/remote access. Most product relationships below come from the README; source excerpts give additional evidence for provider runtime management and storage. Unsampled modules are represented only where the README documents their capabilities.

Main entry points: [`src/backend`](https://github.com/nightly-labs/openbot/tree/main/src/backend) (Agent sessions), [`src/renderer/src`](https://github.com/nightly-labs/openbot/tree/main/src/renderer/src) (Desktop app), [`src/renderer/src/features/agents`](https://github.com/nightly-labs/openbot/tree/main/src/renderer/src/features/agents) (Agent setup), [`packages/ui/src/features/files/StorageOverview.tsx`](https://github.com/nightly-labs/openbot/blob/main/packages/ui/src/features/files/StorageOverview.tsx) (Storage surfaces)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent_runtime["Agent runtime"]
  node_agent_setup["Agent setup"]
  node_runtime_manager["Provider runtimes"]
  node_provider_sessions["Agent sessions"]
end

subgraph group_workspace["Workspace features"]
  node_workspaces["Agent workspaces"]
  node_queues["Message queues"]
  node_team_messaging["Agent messaging"]
  node_shared_channels["Shared channels"]
  node_files["Files and transfers"]
  node_browser["Embedded browser"]
  node_storage_scanner["Storage scanner<br/>[storage-usage.ts]"]
  node_storage_database[("Storage queries")]
  node_storage_ui["Storage surfaces"]
end

subgraph group_access["App and access"]
  node_desktop["Desktop app"]
  node_mobile["Mobile app"]
  node_server["Self-hosted server"]
  node_remote_api["Remote API<br/>[app.ts]"]
  node_remote_signaling["Remote signaling<br/>[signal-service.ts]"]
  node_storage_ipc["Storage IPC"]
end

subgraph group_services["Accounts and services"]
  node_auth_api["Account API<br/>[auth-service.ts]"]
  node_auth_repository[("D1 auth repository")]
end

subgraph group_shared_contracts["Shared contracts"]
  node_storage_contract["Storage wire contract<br/>[ipc-storage.ts]"]
end

node_user(("User"))
node_external_providers{{"AI providers"}}

node_user -->|"uses"| node_desktop
node_user -->|"uses"| node_mobile
node_user -->|"uses"| node_server
node_desktop -->|"creates agents"| node_agent_setup
node_agent_setup -->|"selects runtime"| node_runtime_manager
node_runtime_manager -->|"manages CLIs"| node_external_providers
node_provider_sessions -->|"runs sessions"| node_external_providers
node_agent_setup -->|"starts agents"| node_provider_sessions
node_provider_sessions -->|"uses workspace"| node_workspaces
node_provider_sessions -->|"processes messages"| node_queues
node_provider_sessions -->|"exchanges messages"| node_team_messaging
node_shared_channels -->|"delegates tasks"| node_provider_sessions
node_provider_sessions -->|"transfers files"| node_files
node_provider_sessions -->|"controls browser"| node_browser
node_desktop -->|"connects remotely"| node_remote_api
node_remote_api -->|"uses signaling"| node_remote_signaling
node_desktop -->|"signs in"| node_auth_api
node_auth_api -->|"persists accounts"| node_auth_repository
node_desktop -->|"views storage"| node_storage_ui
node_storage_ui -.->|"requests storage"| node_storage_ipc
node_storage_ipc -->|"runs scans"| node_storage_scanner
node_storage_scanner -->|"reads chat data"| node_storage_database
node_storage_ipc -->|"validates payloads"| node_storage_contract
node_storage_ui -->|"renders usage"| node_storage_contract
node_mobile -->|"uses server"| node_server

click node_desktop "https://github.com/nightly-labs/openbot/tree/main/src/renderer/src"
click node_mobile "https://github.com/nightly-labs/openbot/tree/main/apps/mobile/src"
click node_server "https://github.com/nightly-labs/openbot/tree/main/src/backend"
click node_agent_setup "https://github.com/nightly-labs/openbot/tree/main/src/renderer/src/features/agents"
click node_runtime_manager "https://github.com/nightly-labs/openbot/blob/main/src/main/provider-runtime-manager.ts"
click node_provider_sessions "https://github.com/nightly-labs/openbot/tree/main/src/backend"
click node_workspaces "https://github.com/nightly-labs/openbot/tree/main/src/backend/agent-data"
click node_queues "https://github.com/nightly-labs/openbot/tree/main/src/backend"
click node_team_messaging "https://github.com/nightly-labs/openbot/blob/main/src/backend/messaging/messaging-service.ts"
click node_shared_channels "https://github.com/nightly-labs/openbot/tree/main/src/backend"
click node_files "https://github.com/nightly-labs/openbot/tree/main/packages/ui/src/features/files"
click node_browser "https://github.com/nightly-labs/openbot/tree/main/src/backend"
click node_remote_api "https://github.com/nightly-labs/openbot/blob/main/remote/api/src/app.ts"
click node_remote_signaling "https://github.com/nightly-labs/openbot/blob/main/remote/api/src/signal-service.ts"
click node_auth_api "https://github.com/nightly-labs/openbot/blob/main/apps/auth-api/src/server/auth-service.ts"
click node_auth_repository "https://github.com/nightly-labs/openbot/blob/main/apps/auth-api/src/server/d1-auth-repository.ts"
click node_storage_scanner "https://github.com/nightly-labs/openbot/blob/main/src/backend/storage-usage.ts"
click node_storage_database "https://github.com/nightly-labs/openbot/blob/main/src/backend/database/storage-usage-queries.ts"
click node_storage_ipc "https://github.com/nightly-labs/openbot/blob/main/src/main/ipc/storage-handlers.ts"
click node_storage_ui "https://github.com/nightly-labs/openbot/blob/main/packages/ui/src/features/files/StorageOverview.tsx"
click node_storage_contract "https://github.com/nightly-labs/openbot/blob/main/packages/contracts/src/ipc-storage.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_agent_setup,node_runtime_manager,node_provider_sessions,node_user toneBlue
class node_workspaces,node_queues,node_team_messaging,node_shared_channels,node_files,node_browser,node_storage_scanner,node_storage_database,node_storage_ui toneAmber
class node_desktop,node_mobile,node_server,node_remote_api,node_remote_signaling,node_storage_ipc toneMint
class node_auth_api,node_auth_repository toneRose
class node_storage_contract,node_external_providers toneIndigo
```

## Components

### Agent runtime

- [Agent setup](https://github.com/nightly-labs/openbot/tree/main/src/renderer/src/features/agents): `src/renderer/src/features/agents`
- [Provider runtimes](https://github.com/nightly-labs/openbot/blob/main/src/main/provider-runtime-manager.ts): `src/main/provider-runtime-manager.ts`
- [Agent sessions](https://github.com/nightly-labs/openbot/tree/main/src/backend): `src/backend`

### Workspace features

- [Agent workspaces](https://github.com/nightly-labs/openbot/tree/main/src/backend/agent-data): `src/backend/agent-data`
- [Message queues](https://github.com/nightly-labs/openbot/tree/main/src/backend): `src/backend`
- [Agent messaging](https://github.com/nightly-labs/openbot/blob/main/src/backend/messaging/messaging-service.ts): `src/backend/messaging/messaging-service.ts`
- [Shared channels](https://github.com/nightly-labs/openbot/tree/main/src/backend): `src/backend`
- [Files and transfers](https://github.com/nightly-labs/openbot/tree/main/packages/ui/src/features/files): `packages/ui/src/features/files`
- [Embedded browser](https://github.com/nightly-labs/openbot/tree/main/src/backend): `src/backend`
- [Storage scanner](https://github.com/nightly-labs/openbot/blob/main/src/backend/storage-usage.ts): `src/backend/storage-usage.ts`
- [Storage queries](https://github.com/nightly-labs/openbot/blob/main/src/backend/database/storage-usage-queries.ts): `src/backend/database/storage-usage-queries.ts`
- [Storage surfaces](https://github.com/nightly-labs/openbot/blob/main/packages/ui/src/features/files/StorageOverview.tsx): `packages/ui/src/features/files/StorageOverview.tsx`

### App and access

- [Desktop app](https://github.com/nightly-labs/openbot/tree/main/src/renderer/src): `src/renderer/src`
- [Mobile app](https://github.com/nightly-labs/openbot/tree/main/apps/mobile/src): `apps/mobile/src`
- [Self-hosted server](https://github.com/nightly-labs/openbot/tree/main/src/backend): `src/backend`
- [Remote API](https://github.com/nightly-labs/openbot/blob/main/remote/api/src/app.ts): `remote/api/src/app.ts`
- [Remote signaling](https://github.com/nightly-labs/openbot/blob/main/remote/api/src/signal-service.ts): `remote/api/src/signal-service.ts`
- [Storage IPC](https://github.com/nightly-labs/openbot/blob/main/src/main/ipc/storage-handlers.ts): `src/main/ipc/storage-handlers.ts`

### Accounts and services

- [Account API](https://github.com/nightly-labs/openbot/blob/main/apps/auth-api/src/server/auth-service.ts): `apps/auth-api/src/server/auth-service.ts`
- [D1 auth repository](https://github.com/nightly-labs/openbot/blob/main/apps/auth-api/src/server/d1-auth-repository.ts): `apps/auth-api/src/server/d1-auth-repository.ts`

### Shared contracts

- [Storage wire contract](https://github.com/nightly-labs/openbot/blob/main/packages/contracts/src/ipc-storage.ts): `packages/contracts/src/ipc-storage.ts`

### Other components

- **User**
- **AI providers**

## Connections

- User → Desktop app: uses
- User → Mobile app: uses
- User → Self-hosted server: uses
- Desktop app → Agent setup: creates agents
- Agent setup → Provider runtimes: selects runtime (evidence: `src/main/provider-runtime-manager.ts`)
- Provider runtimes → AI providers: manages CLIs
- Agent sessions → AI providers: runs sessions
- Agent setup → Agent sessions: starts agents
- Agent sessions → Agent workspaces: uses workspace
- Agent sessions → Message queues: processes messages
- Agent sessions → Agent messaging: exchanges messages
- Shared channels → Agent sessions: delegates tasks
- Agent sessions → Files and transfers: transfers files
- Agent sessions → Embedded browser: controls browser
- Desktop app → Remote API: connects remotely
- Remote API → Remote signaling: uses signaling (evidence: `remote/api/src/app.ts`)
- Desktop app → Account API: signs in
- Account API → D1 auth repository: persists accounts (evidence: `apps/auth-api/src/server/auth-service.ts`)
- Desktop app → Storage surfaces: views storage
- Storage surfaces → Storage IPC: requests storage
- Storage IPC → Storage scanner: runs scans (evidence: `src/main/ipc/storage-handlers.ts`)
- Storage scanner → Storage queries: reads chat data (evidence: `src/backend/storage-usage.ts`)
- Storage IPC → Storage wire contract: validates payloads (evidence: `src/main/ipc/storage-handlers.ts`)
- Storage surfaces → Storage wire contract: renders usage (evidence: `packages/ui/src/features/files/StorageOverview.tsx`)
- Mobile app → Self-hosted server: uses server
