How maxmasai/maxdots works
Maxdots is a self-hosted workspace for personal AI agents (“dots”), combining chat, channels, computer-use automation, integrations, and voice. The main workflow is a user sending a task in chat, server actions dispatching it to the agent runtime, and the dot working with its configured model and computer; persistent workspace data and events support the UI. README capabilities also include multi-agent channels, approvals, app integrations, and persistent voice calls. Source excerpts do not expose every runtime dispatch, so uncertain links are omitted or marked unverified.
Main entry points: actions.ts Server actions · repo.ts Workspace repository · runtime.ts Agent runtime · vault.ts Credential vault
Components 21
Workspace UI
- Chat workspace
src/components/Chat.tsx - Channels
src/components/ChannelView.tsx - Calls hub
src/components/CallsView.tsx - Settings
src/components/SettingsView.tsx - Dot avatars
src/components/DotOrb.tsx
Agent orchestration
- Server actions
src/app/actions.ts - Agent runtime
src/server/agent/runtime.ts - Model selection
src/server/agent/client.ts
Dot capabilities
- Computer modes
src/server/computer/index.ts - Browser automation
src/server/computer/browser.ts - App integrations
src/server/composio.ts - App triggers
src/server/triggers.ts - Persistent voice
src/lib/voiceCall.ts
Persistence and events
- Workspace repository
src/server/repo.ts - SQLite database
src/server/db.ts - Credential vault
src/server/vault.ts - Event bus
src/server/bus.ts - Workspace snapshot
src/server/snapshot.ts - Client state
src/lib/store.ts - Event stream API
src/app/api/events/route.ts
Other components
- User
Connections 26
- User → Chat workspace: sends task
- Chat workspace → Server actions: submits messages
src/components/Chat.tsx - Server actions → Agent runtime: dispatches task
src/app/actions.ts - Server actions → Workspace repository: manages workspace
src/app/actions.ts - Server actions → Computer modes: uses computer
src/app/actions.ts - Server actions → Credential vault: saves credentials
src/app/actions.ts - Server actions → Event bus: emits updates
src/app/actions.ts - Agent runtime → Computer modes: uses tools
- Agent runtime → Model selection: selects model
- Model selection → Credential vault: reads secrets
src/server/agent/client.ts - Model selection → SQLite database: reads settings
src/server/agent/client.ts - Computer modes → Browser automation: delegates browser work
src/server/computer/index.ts - Workspace repository → SQLite database: reads and writes
src/server/repo.ts - Workspace repository → Event bus: emits changes
src/server/repo.ts - Credential vault → Workspace repository: stores encrypted passwords
src/server/vault.ts - Settings → Server actions: updates configuration
src/components/SettingsView.tsx - Calls hub → Persistent voice: starts calls
src/components/CallsView.tsx - Persistent voice → Server actions: sends voice tasks
src/lib/voiceCall.ts - Channels → Server actions: coordinates conversations
- App integrations → Credential vault: seals tokens
src/server/composio.ts - App triggers → Agent runtime: starts agent tasks
- Event stream API → Event bus: subscribes to events
src/app/api/events/route.ts - Event stream API → Workspace snapshot: loads initial state
src/app/api/events/route.ts - Client state → Event stream API: opens event stream
- Workspace snapshot → Workspace repository: collects workspace data
src/server/snapshot.ts - Chat workspace → Dot avatars: renders dots
src/components/Chat.tsx