# gethouston/houston architecture

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

- Interactive diagram: https://gitdiagram.com/gethouston/houston
- Repository: https://github.com/gethouston/houston

## Overview

Houston is an AI-agent platform spanning desktop, browser, and managed-cloud experiences. The main workflow is to enter a workspace, create or select agents, then use chat and a mission board to do work with files, integrations, and routines. Shared engine/runtime services handle agent execution and model access; desktop-specific components supervise the local host and bridge OS capabilities. The README documents several product flows, while sampled source gives stronger implementation evidence for engine startup and authentication; other links are limited to documented relationships.

Main entry points: [`app/src/components/agents-home/agents-home-view.tsx`](https://github.com/gethouston/houston/blob/main/app/src/components/agents-home/agents-home-view.tsx) (Agent management), [`app/src/App.tsx`](https://github.com/gethouston/houston/blob/main/app/src/App.tsx) (Desktop app), [`packages/runtime/src/main.ts`](https://github.com/gethouston/houston/blob/main/packages/runtime/src/main.ts) (Agent runtime), [`app/src/app-workspace.tsx`](https://github.com/gethouston/houston/blob/main/app/src/app-workspace.tsx) (Workspaces)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Product clients"]
  node_desktop["Desktop app<br/>[App.tsx]"]
  node_web["Browser app<br/>[main.tsx]"]
  node_enginegate["Engine gate<br/>[engine-gate.tsx]"]
  node_supervisor["Host supervisor"]
  node_osbridge["OS bridge<br/>[os-bridge.ts]"]
end

subgraph group_work["Workspace work"]
  node_workspace["Workspaces<br/>[app-workspace.tsx]"]
  node_agents["Agent management"]
  node_chat["Agent chat<br/>[assistant-view.tsx]"]
  node_board["Mission board<br/>[use-board-drag.ts]"]
  node_files["Agent files"]
  node_integrations["Integrations<br/>[manager.ts]"]
  node_routines["Routines<br/>[routine-screen.tsx]"]
  node_sharing["Teams and sharing"]
end

subgraph group_engine["Engine execution"]
  node_host["Houston host<br/>[route.ts]"]
  node_runtime["Agent runtime<br/>[main.ts]"]
  node_sdk["Engine SDK<br/>[engine-clients.ts]"]
  node_runtimeclient["Runtime client<br/>[client.ts]"]
end

subgraph group_identity["Identity and providers"]
  node_identity["Session identity<br/>[index.ts]"]
  node_sessionstore["Session storage"]
  node_credentials[("Model credentials<br/>[storage.ts]")]
  node_providers["Model providers<br/>[storage.ts]"]
end

subgraph group_catalog["Agent catalog"]
  node_agentstore["Agent catalog<br/>[page.tsx]"]
  node_agentstoreapi["Catalog API<br/>[route.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_desktop
node_user -->|"uses"| node_web
node_desktop -->|"gates access"| node_enginegate
node_enginegate -->|"loads session"| node_identity
node_enginegate -.->|"waits for engine"| node_supervisor
node_supervisor -->|"spawns and probes"| node_host
node_desktop -.->|"bridges OS calls"| node_osbridge
node_desktop -->|"opens workspace"| node_workspace
node_web -->|"opens workspace"| node_workspace
node_workspace -->|"organizes"| node_agents
node_agents -->|"starts conversations"| node_chat
node_agents -->|"assigns missions"| node_board
node_agents -->|"manages files"| node_files
node_agents -->|"uses connected apps"| node_integrations
node_agents -->|"configures schedules"| node_routines
node_workspace -->|"shares agents"| node_sharing
node_host -->|"hosts runtime"| node_runtime
node_runtime -.->|"uses engine clients"| node_sdk
node_sdk -->|"creates clients"| node_runtimeclient
node_identity -.->|"persists sessions"| node_sessionstore
node_sessionstore -->|"uses keychain bridge"| node_osbridge
node_runtime -->|"resolves credentials"| node_credentials
node_runtime -->|"dispatches requests"| node_providers
node_user -.->|"browses agents"| node_agentstore
node_agentstore -.->|"downloads bundles"| node_agentstoreapi

click node_desktop "https://github.com/gethouston/houston/blob/main/app/src/App.tsx"
click node_web "https://github.com/gethouston/houston/blob/main/packages/web/src/main.tsx"
click node_enginegate "https://github.com/gethouston/houston/blob/main/app/src/components/shell/engine-gate.tsx"
click node_supervisor "https://github.com/gethouston/houston/blob/main/app/src-tauri/src/engine_supervisor.rs"
click node_osbridge "https://github.com/gethouston/houston/blob/main/app/src/lib/os-bridge.ts"
click node_workspace "https://github.com/gethouston/houston/blob/main/app/src/app-workspace.tsx"
click node_agents "https://github.com/gethouston/houston/blob/main/app/src/components/agents-home/agents-home-view.tsx"
click node_chat "https://github.com/gethouston/houston/blob/main/app/src/components/assistant/assistant-view.tsx"
click node_board "https://github.com/gethouston/houston/blob/main/ui/board/src/use-board-drag.ts"
click node_files "https://github.com/gethouston/houston/blob/main/app/src/components/agent/agent-files/use-agent-files.tsx"
click node_integrations "https://github.com/gethouston/houston/blob/main/packages/host/src/integrations/custom/manager.ts"
click node_routines "https://github.com/gethouston/houston/blob/main/app/src/components/agent/routine-screen.tsx"
click node_sharing "https://github.com/gethouston/houston/blob/main/app/src/components/agent/agent-share-dialog.tsx"
click node_host "https://github.com/gethouston/houston/blob/main/packages/host/src/proxy/route.ts"
click node_runtime "https://github.com/gethouston/houston/blob/main/packages/runtime/src/main.ts"
click node_sdk "https://github.com/gethouston/houston/blob/main/packages/sdk/src/engine-clients.ts"
click node_runtimeclient "https://github.com/gethouston/houston/blob/main/packages/runtime-client/src/client.ts"
click node_identity "https://github.com/gethouston/houston/blob/main/app/src/lib/identity/index.ts"
click node_sessionstore "https://github.com/gethouston/houston/blob/main/app/src/lib/identity/session-storage-kv.ts"
click node_credentials "https://github.com/gethouston/houston/blob/main/packages/runtime/src/auth/storage.ts"
click node_providers "https://github.com/gethouston/houston/blob/main/packages/runtime/src/auth/storage.ts"
click node_agentstore "https://github.com/gethouston/houston/blob/main/agentstore/src/app/page.tsx"
click node_agentstoreapi "https://github.com/gethouston/houston/blob/main/agentstore/src/app/api/agents/%5Bagent%5D/bundle/route.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_desktop,node_web,node_enginegate,node_supervisor,node_osbridge,node_user toneBlue
class node_workspace,node_agents,node_chat,node_board,node_files,node_integrations,node_routines,node_sharing toneAmber
class node_host,node_runtime,node_sdk,node_runtimeclient toneMint
class node_identity,node_sessionstore,node_credentials,node_providers toneRose
class node_agentstore,node_agentstoreapi toneIndigo
```

## Components

### Product clients

- [Desktop app](https://github.com/gethouston/houston/blob/main/app/src/App.tsx): `app/src/App.tsx`
- [Browser app](https://github.com/gethouston/houston/blob/main/packages/web/src/main.tsx): `packages/web/src/main.tsx`
- [Engine gate](https://github.com/gethouston/houston/blob/main/app/src/components/shell/engine-gate.tsx): `app/src/components/shell/engine-gate.tsx`
- [Host supervisor](https://github.com/gethouston/houston/blob/main/app/src-tauri/src/engine_supervisor.rs): `app/src-tauri/src/engine_supervisor.rs`
- [OS bridge](https://github.com/gethouston/houston/blob/main/app/src/lib/os-bridge.ts): `app/src/lib/os-bridge.ts`

### Workspace work

- [Workspaces](https://github.com/gethouston/houston/blob/main/app/src/app-workspace.tsx): `app/src/app-workspace.tsx`
- [Agent management](https://github.com/gethouston/houston/blob/main/app/src/components/agents-home/agents-home-view.tsx): `app/src/components/agents-home/agents-home-view.tsx`
- [Agent chat](https://github.com/gethouston/houston/blob/main/app/src/components/assistant/assistant-view.tsx): `app/src/components/assistant/assistant-view.tsx`
- [Mission board](https://github.com/gethouston/houston/blob/main/ui/board/src/use-board-drag.ts): `ui/board/src/use-board-drag.ts`
- [Agent files](https://github.com/gethouston/houston/blob/main/app/src/components/agent/agent-files/use-agent-files.tsx): `app/src/components/agent/agent-files/use-agent-files.tsx`
- [Integrations](https://github.com/gethouston/houston/blob/main/packages/host/src/integrations/custom/manager.ts): `packages/host/src/integrations/custom/manager.ts`
- [Routines](https://github.com/gethouston/houston/blob/main/app/src/components/agent/routine-screen.tsx): `app/src/components/agent/routine-screen.tsx`
- [Teams and sharing](https://github.com/gethouston/houston/blob/main/app/src/components/agent/agent-share-dialog.tsx): `app/src/components/agent/agent-share-dialog.tsx`

### Engine execution

- [Houston host](https://github.com/gethouston/houston/blob/main/packages/host/src/proxy/route.ts): `packages/host/src/proxy/route.ts`
- [Agent runtime](https://github.com/gethouston/houston/blob/main/packages/runtime/src/main.ts): `packages/runtime/src/main.ts`
- [Engine SDK](https://github.com/gethouston/houston/blob/main/packages/sdk/src/engine-clients.ts): `packages/sdk/src/engine-clients.ts`
- [Runtime client](https://github.com/gethouston/houston/blob/main/packages/runtime-client/src/client.ts): `packages/runtime-client/src/client.ts`

### Identity and providers

- [Session identity](https://github.com/gethouston/houston/blob/main/app/src/lib/identity/index.ts): `app/src/lib/identity/index.ts`
- [Session storage](https://github.com/gethouston/houston/blob/main/app/src/lib/identity/session-storage-kv.ts): `app/src/lib/identity/session-storage-kv.ts`
- [Model credentials](https://github.com/gethouston/houston/blob/main/packages/runtime/src/auth/storage.ts): `packages/runtime/src/auth/storage.ts`
- [Model providers](https://github.com/gethouston/houston/blob/main/packages/runtime/src/auth/storage.ts): `packages/runtime/src/auth/storage.ts`

### Agent catalog

- [Agent catalog](https://github.com/gethouston/houston/blob/main/agentstore/src/app/page.tsx): `agentstore/src/app/page.tsx`
- [Catalog API](https://github.com/gethouston/houston/blob/main/agentstore/src/app/api/agents/%5Bagent%5D/bundle/route.ts): `agentstore/src/app/api/agents/[agent]/bundle/route.ts`

### Other components

- **User**

## Connections

- User → Desktop app: uses (evidence: `README.md`)
- User → Browser app: uses (evidence: `README.md`)
- Desktop app → Engine gate: gates access (evidence: `app/src/components/shell/engine-gate.tsx`)
- Engine gate → Session identity: loads session (evidence: `app/src/components/shell/engine-gate.tsx`)
- Engine gate → Host supervisor: waits for engine
- Host supervisor → Houston host: spawns and probes (evidence: `app/src-tauri/src/engine_supervisor.rs`)
- Desktop app → OS bridge: bridges OS calls
- Desktop app → Workspaces: opens workspace (evidence: `README.md`)
- Browser app → Workspaces: opens workspace (evidence: `README.md`)
- Workspaces → Agent management: organizes (evidence: `README.md`)
- Agent management → Agent chat: starts conversations (evidence: `README.md`)
- Agent management → Mission board: assigns missions (evidence: `README.md`)
- Agent management → Agent files: manages files (evidence: `README.md`)
- Agent management → Integrations: uses connected apps (evidence: `README.md`)
- Agent management → Routines: configures schedules (evidence: `README.md`)
- Workspaces → Teams and sharing: shares agents (evidence: `README.md`)
- Houston host → Agent runtime: hosts runtime (evidence: `README.md`)
- Agent runtime → Engine SDK: uses engine clients
- Engine SDK → Runtime client: creates clients (evidence: `packages/sdk/src/engine-clients.ts`)
- Session identity → Session storage: persists sessions
- Session storage → OS bridge: uses keychain bridge (evidence: `app/src/lib/identity/session-storage-kv.ts`)
- Agent runtime → Model credentials: resolves credentials (evidence: `packages/runtime/src/auth/storage.ts`)
- Agent runtime → Model providers: dispatches requests (evidence: `packages/runtime/src/auth/storage.ts`)
- User → Agent catalog: browses agents
- Agent catalog → Catalog API: downloads bundles