How gethouston/houston works
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: agents-home-view.tsx Agent management · App.tsx Desktop app · main.ts Agent runtime · app-workspace.tsx Workspaces
Components 24
Product clients
- Desktop app
app/src/App.tsx - Browser app
packages/web/src/main.tsx - Engine gate
app/src/components/shell/engine-gate.tsx - Host supervisor
app/src-tauri/src/engine_supervisor.rs - OS bridge
app/src/lib/os-bridge.ts
Workspace work
- Workspaces
app/src/app-workspace.tsx - Agent management
app/src/components/agents-home/agents-home-view.tsx - Agent chat
app/src/components/assistant/assistant-view.tsx - Mission board
ui/board/src/use-board-drag.ts - Agent files
app/src/components/agent/agent-files/use-agent-files.tsx - Integrations
packages/host/src/integrations/custom/manager.ts - Routines
app/src/components/agent/routine-screen.tsx - Teams and sharing
app/src/components/agent/agent-share-dialog.tsx
Engine execution
- Houston host
packages/host/src/proxy/route.ts - Agent runtime
packages/runtime/src/main.ts - Engine SDK
packages/sdk/src/engine-clients.ts - Runtime client
packages/runtime-client/src/client.ts
Identity and providers
- Session identity
app/src/lib/identity/index.ts - Session storage
app/src/lib/identity/session-storage-kv.ts - Model credentials
packages/runtime/src/auth/storage.ts - Model providers
packages/runtime/src/auth/storage.ts
Agent catalog
- Agent catalog
agentstore/src/app/page.tsx - Catalog API
agentstore/src/app/api/agents/[agent]/bundle/route.ts
Other components
- User
Connections 25
- User → Desktop app: uses
README.md - User → Browser app: uses
README.md - Desktop app → Engine gate: gates access
app/src/components/shell/engine-gate.tsx - Engine gate → Session identity: loads session
app/src/components/shell/engine-gate.tsx - Engine gate → Host supervisor: waits for engine
- Host supervisor → Houston host: spawns and probes
app/src-tauri/src/engine_supervisor.rs - Desktop app → OS bridge: bridges OS calls
- Desktop app → Workspaces: opens workspace
README.md - Browser app → Workspaces: opens workspace
README.md - Workspaces → Agent management: organizes
README.md - Agent management → Agent chat: starts conversations
README.md - Agent management → Mission board: assigns missions
README.md - Agent management → Agent files: manages files
README.md - Agent management → Integrations: uses connected apps
README.md - Agent management → Routines: configures schedules
README.md - Workspaces → Teams and sharing: shares agents
README.md - Houston host → Agent runtime: hosts runtime
README.md - Agent runtime → Engine SDK: uses engine clients
- Engine SDK → Runtime client: creates clients
packages/sdk/src/engine-clients.ts - Session identity → Session storage: persists sessions
- Session storage → OS bridge: uses keychain bridge
app/src/lib/identity/session-storage-kv.ts - Agent runtime → Model credentials: resolves credentials
packages/runtime/src/auth/storage.ts - Agent runtime → Model providers: dispatches requests
packages/runtime/src/auth/storage.ts - User → Agent catalog: browses agents
- Agent catalog → Catalog API: downloads bundles