How agentark-ai/agentark works
1. Repository shape
- This is a multi-runtime monorepo centered on a Rust backend (src/) with a TypeScript React frontend (frontend/), plus mobile/desktop companion clients (clients/companion/), channel bridges (bridges/), and Docker-based deployment/runtime files.
- The codebase is organized as a local AI operating system rather than a single app: chat, tasks, memory, integrations, automation, self-improvement, and observability are all first-class subsystems.
2. Primary control plane
- The Rust server is the main control plane. It exposes many HTTP API groups under src/channels/http/ for core chat, runtime, admin, analytics, app control, integrations, automation, tunnels, and action APIs.
- The web UI in frontend/ talks to this backend through a client layer (frontend/src/api/client.ts) and renders the main Mission Control surfaces such as chat, settings, memory, reflect, sentinel, evolve, and pulse.
3. Core domain layers
- src/core/ contains the product’s main logic, split into domains like agent, automation, connectivity, knowledge, model, orchestration, runtime, self_evolve, swarm, and platform.
- These layers are where decisions are made: prompt construction, memory retrieval, task routing, model selection/failover, background learning, policy enforcement, and orchestration of tool execution.
4. Agent loop and reasoning flow
- The agent path starts with conversation/state handling in src/core/agent/conversation/, then moves through prompt/spine construction in src/core/agent/spine/, runtime execution in src/core/agent/runtime/, and memory/ops helpers in src/core/agent/operations/.
- The model layer (src/core/model/) abstracts provider access, context budgeting, failover, and prompt policy so the system can work with Ollama or remote LLM APIs without changing the higher-level orchestration.
5. Execution and tool isolation
- Tool execution is separated into src/runtime/action_runtime/ and src/runtime/, with support for native execution, CLI execution, code execution, browser/web access, Docker-backed WASM execution, and governance/authorization checks.
- This boundary is important: the agent does not directly “do everything” inside the model loop. Actions are validated, authorized, executed, and then recorded with proofs/traces for later review.
6. Security and trust boundaries
- Security is explicit and layered: src/security/ handles abuse tracking, trust boundaries, action guards, outbound filtering, tool-argument validation, privacy normalization/PII handling, and review policies.
- Secrets are managed through encrypted storage (src/crypto/, src/storage/encrypted.rs, src/core/runtime/config/secrets.rs), and approvals/guards sit between model intent and real-world effects.
7. Persistence and local data model
- The app is backed by a substantial local persistence layer in src/storage/, which includes entities and repositories for conversations, messages, documents, memory, tasks, runs, traces, approval logs, notifications, webhooks, browser sessions, and usage.
- This suggests a “local workspace database” architecture: operational state, audit history, memory, and configuration all live in the local stack, primarily behind Postgres plus file-backed artifacts in the data volume.
8. Automation, background work, and supervision
- Long-running behavior is handled by src/core/automation/ and src/core/connectivity/channels/ with watchers, runs, background sessions, task routing, and reminder/follow-up flows.
- The Sentinel/Pulse style supervision surfaces are backed by runtime health checks, readiness, update operations, and monitoring models in src/core/runtime/operations/ and src/sentinel/, making background work observable and restartable.
9. Integrations and external connectivity
- Integrations are split into domain-specific modules under src/integrations/ for browsers, messaging, productivity, devices, commerce, Google, media, and more, while src/channels/messaging/ covers outbound messaging platforms like Slack, Telegram, WhatsApp, Teams, Matrix, Signal, and others.
- Webhooks, custom APIs, MCP, and external gateways are handled as separate integration surfaces, which keeps third-party connectivity out of the core agent loop and makes each connector an explicit boundary.
10. Companion devices and paired clients
- The clients/companion/ subtree contains native companions for Android, iOS, desktop, and a minimal Python custom-device client, all of which speak a shared companion protocol schema in clients/companion/protocol/.
- These clients appear to be for authenticated device pairing and scoped remote command/control, with token storage and websocket clients showing that the backend remains the authority while devices act as constrained endpoints.
11. Bridges and specialized sidecars
- The bridges/ directory contains standalone services for capabilities that are awkward to embed directly in Rust: Playwright/browser automation, WhatsApp bridging, voice bridging, and a Python-based GEPA optimizer bridge.
- These are operationally separate containers/processes, which keeps heavyweight browser/audio/optimizer dependencies out of the main Rust binary while still exposing them to the control plane.
12. Self-evolution and learning loop
- src/core/self_evolve/ is the learning subsystem: it tracks opportunities, benchmarks, gates, routing/prompt evolution, optimizer integration, and runtime self-tuning.
- This is tightly coupled to memory, traces, usage, and evaluation data from storage/repositories, so the system can propose and validate changes to prompts, routing, and context-saving behavior rather than learning only inside the model session.
13. Frontend architecture
- The frontend is a large React/Vite application with many feature panels and pages: chat, tasks, memory, settings, analytics, integrations, voice, apps, traces, and the Ark Core surfaces.
- It is presentation-heavy and stateful at the UI layer, but it relies on the Rust backend for durable state, action execution, and authority. The UI is effectively the operator console for the entire local AI stack.
14. Deployment/runtime topology
- The repository is designed for Docker Compose as the default deployment shape, with Postgres, the Rust services, the frontend, and supporting containers started together.
- The README and compose files indicate optional low-memory mode, managed backups, remote access/tunnels, and bundled runtime dependencies such as browser tooling, Docker CLI, and embeddings services. This makes the architecture a self-hosted local cluster rather than a single process.
15. What to draw in an architecture diagram
- Model the system as: UI/client surfaces on top, Rust control plane APIs in the middle, then core domain services for agent logic, memory, automation, self-evolve, and integrations, with execution/runtime sandboxes and storage/security as cross-cutting layers.
- Add separate external-boundary boxes for LLM providers, messaging platforms, browser/web services, Google/productivity services, companion devices, and Docker/WASM execution, because those are the main places data leaves or returns to the system.
Main entry points: client.ts API client · storage Storage · agent Agent loop · action_runtime Action runtime
Components 26
Frontend
React/Vite operator console and client layer
- Mission Control · Main operator console for chat, memory, settings, observability, and evolution
frontend/src/App.tsx - API client · Frontend backend client used by all major surfaces
frontend/src/api/client.ts - UI panels · Chat, tasks, memory, reflect, sentinel, evolve, pulse, integrations, and analytics surfaces
frontend/src/components/pages
Rust control plane
HTTP APIs, orchestration, and backend services
- Core APIs · Chat, conversation, auth, middleware, notifications, and core server utilities
src/channels/http/core_api - Runtime APIs · Memory, documents, settings, browser profiles, model failover, and voice/runtime control
src/channels/http/runtime_api - App APIs · App serving, companion control, suggestions, UI control, ArkOrbit, and ArkPulse
src/channels/http/app_api - Automation APIs · Automation, autonomy, reflect, evolution, swarm, and sentinel surfaces
src/channels/http/automation_api - Integration APIs · Integrations, gateway ops, sync, monitoring, webhooks, and custom messaging channels
src/channels/http/integration_api - Admin APIs · Security, profiles, secrets, sender verification, and locked control
src/channels/http/admin_api
Core domains
Agent, memory, automation, model, and learning logic
- Agent loop · Conversation handling, prompt spine, runtime execution, and operations
src/core/agent - Model layer · Provider access, context budgeting, failover, prompt policy, and sanitization
src/core/model - Orchestration · Action catalog, planning, pipeline coordination, and execution control
src/core/orchestration - Automation · Tasks, watchers, runs, autonomy, and background sessions
src/core/automation - Knowledge · Embeddings, document search, learning, deduplication, and memory schema
src/core/knowledge - Self-evolve · Opportunities, benchmarks, prompt and routing evolution, gates, and self-tuning
src/core/self_evolve - Swarm · Specialist agents, coordination bus, and shared swarm state
src/core/swarm
Execution and trust
Sandboxes, security boundaries, and persistence
- Action runtime · Native, CLI, code, WASM/docker, web, and governed action execution
src/runtime/action_runtime - Security · Abuse tracking, privacy normalization, action guards, tool validation, and review policies
src/security - Storage · Encrypted storage, entities, repositories, audit logs, memory, tasks, traces, and usage
src/storage - Connectivity · Browser, messaging, email delivery, sender verification, gateway, and integration sync
src/core/connectivity
External boundaries
Outside systems and companion endpoints
- Companions · Android, iOS, desktop, and custom-device clients speaking the companion protocol
clients/companion - Messaging platforms · Slack, Telegram, WhatsApp, Teams, Signal, Matrix, and related outbound platforms
src/channels/messaging - LLM providers · Remote or local model backends used through the model abstraction
- Browser/web · Web access, browser sessions, and browser automation side effects
src/integrations/browser - Google services · Workspace, calendar, Gmail, analytics, search, and places integrations
src/integrations/google - Sidecar bridges · Playwright, voice, WhatsApp bridge, and GEPA optimizer sidecars
bridges
Connections 31
- Mission Control → API client: calls · UI uses the shared API client for backend communication
- UI panels → API client: loads data · Feature panels fetch and mutate backend state
- API client → Core APIs: chat/control · Primary UI traffic enters the core HTTP API group
- API client → Runtime APIs: runtime state · Settings, memory, browser, and voice control flows
- API client → App APIs: app surfaces · Mission Control and companion/app panels use app APIs
- API client → Automation APIs: supervision · Autonomy, reflect, evolve, and swarm panels query automation APIs
- API client → Integration APIs: connectors · Integrations and webhooks are managed through integration APIs
- API client → Admin APIs: admin · Security and secrets surfaces use admin APIs
- Core APIs → Agent loop: drives · Conversation and control endpoints invoke the agent loop
- Runtime APIs → Knowledge: memory · Runtime endpoints expose memory and document retrieval
- Runtime APIs → Model layer: model control · Model settings and failover are mediated through runtime APIs
- App APIs → Companions: pairing/control · Companion device control is surfaced through app APIs
- Automation APIs → Automation: supervises · Automation and autonomy endpoints manage background work
- Automation APIs → Self-evolve: evolution · Reflect/evolve endpoints feed the learning subsystem
- Integration APIs → Connectivity: routes · Integration and gateway APIs map to connectivity services
- Admin APIs → Security: enforces · Administrative control is constrained by trust and security policy
- Agent loop → Model layer: queries · The agent loop builds prompts and calls the model abstraction
- Agent loop → Orchestration: plans · Tooling and task execution are coordinated through orchestration
- Agent loop → Knowledge: retrieves · Conversation state and memory retrieval inform reasoning
- Orchestration → Action runtime: executes · Planned actions are validated and run in isolated runtimes
- Action runtime → Security: checks · Execution is gated by authorization, privacy, and review policies
- Action runtime → Storage: records · Runs, proofs, traces, and artifacts are persisted for auditability
- Knowledge → Storage: reads/writes · Memory, documents, and learning data are persisted locally
- Automation → Storage: tracks · Background sessions, tasks, runs, and watchers are stored
- Self-evolve → Storage: benchmarks · Opportunities, evals, and ledgers use stored history and traces
- Swarm → Storage: state · Swarm coordination and agent state are persisted
- Connectivity → Messaging platforms: delivers · Outbound messaging connectors bridge to external platforms
- Connectivity → Browser/web: browser · Browser sessions and web automation cross the web boundary
- Connectivity → Google services: synchronizes · Google integrations connect productivity and analytics services
- Action runtime → Sidecar bridges: sidecars · Heavyweight browser, voice, and optimizer capabilities live in bridges
- Model layer → LLM providers: calls · LLM access is abstracted behind provider integrations