How zeraix/zeraix works
Zeraix is a local-first AI desktop workspace. The main workflow is a user sending a task in chat, the agent preparing model context and running turns, and tools acting on files or other resources under configurable approval and sandbox policies. Local model management and inference are central, with cloud providers optional. Separate product branches support recurring workflows, MCP and plugins, document skills, generated and uploaded media, and customizable skins. README capabilities guide this map; unsampled implementation details are represented only where the tree supports a path, and uncertain wiring is omitted.
Main entry points: runtimeTurn.ts Turn runtime · page.tsx Chat workspace · agentLoop.ts Agent loop · server.rs Rust Agent Runtime
Components 26
Workspace UI
- Chat workspace
src/app/agent/chat/page.tsx - Turn coordination
src/app/agent/chat/turnRound.ts - Media library
src/lib/ai/mediaLibrary.ts - Generation services
src/lib/ai/generation/index.ts - Skin packages
electron/skins/engine.mjs
Agent execution
- Context builder
src/lib/agent/contextManager.ts - Agent loop
src/lib/agent/agentLoop.ts - Turn runtime
src/lib/agent/runtimeTurn.ts - Runtime boundary
src/lib/agent/runtimeBoundary.ts - Rust Agent Runtime
runtime/crates/agent-runtime/src/server.rs - Tool permissions
runtime/crates/agent-permission/src/lib.rs - Conversation storage
electron/store/conversationStore.mjs
Models and inference
- Model library
src/app/agent/models/page.tsx - Model registry
src/lib/ai/modelRegistry.ts - Local model manager
electron/llm/localModels.mjs - Local inference server
electron/llm/localServer.mjs - Cloud model access
src/lib/ai/llm.ts
Tools and extensions
- File tools
runtime/crates/agent-tools/src/lib.rs - Sandbox execution
electron/tools/sandbox/engine.mjs - MCP connections
electron/mcp/client.mjs - Plugin system
electron/plugins/store.mjs - Document skills
src/lib/ai/skills/runtime.ts
Workflow automation
- Workflow editor
src/app/agent/automation/WorkflowEditor.tsx - Run management
electron/automation/executionManager.mjs - Workflow data
electron/automation/db.mjs
Other components
- User
Connections 26
- User → Chat workspace: sends task
- Chat workspace → Turn coordination: starts turn
- Turn coordination → Context builder: prepares context
- Turn coordination → Agent loop: coordinates turn
- Agent loop → Turn runtime: runs turn
- Turn runtime → Context builder: builds model input
- Turn runtime → Cloud model access: requests model
- Model library → Model registry: selects model
- Model registry → Local model manager: manages local models
- Local model manager → Local inference server: starts inference
- Turn runtime → Runtime boundary: dispatches tool calls
- Runtime boundary → Rust Agent Runtime: sends runtime requests
- Rust Agent Runtime → Tool permissions: checks capabilities
- Rust Agent Runtime → File tools: dispatches tools
- File tools → Sandbox execution: runs commands
- Rust Agent Runtime → MCP connections: uses MCP tools
- Turn runtime → Conversation storage: persists conversation
- Workflow editor → Run management: configures and runs
- Run management → Workflow data: records run state
- Agent loop → Document skills: uses skills
- Agent loop → Plugin system: uses extensions
- Chat workspace → Media library: organizes assets
- Chat workspace → Generation services: requests generation
- User → Model library: chooses models
- User → Workflow editor: creates workflows
- User → Skin packages: customizes appearance