Mobile Architecture (Capacitor)
Relevant source files
The following files were used as context for generating this wiki page:
The mobile architecture uses Capacitor v7 to bridge web-based assets into native Android and iOS environments. This system allows the Agent Studio MCP Engine to operate as a native mobile application while maintaining a shared core logic and user interface.
Capacitor wraps the Vite-built web application, providing access to native device features and enabling cross-device synchronization through a secure Sync Cluster.
Sources: BUILDING.md:12-14, package.json:28-32
Platform Support and Requirements
The mobile implementation targets two primary operating systems using Capacitor-specific toolchains.
| Platform | Toolchain | Output Format | Requirements |
|---|---|---|---|
| Android | Capacitor v7 + Android Studio | .apk / .aab | JDK 17+, Android Studio, AVD for testing |
| iOS | Capacitor v7 + Xcode | .ipa | Xcode 15+, CocoaPods, macOS host |
Sources: BUILDING.md:3-10, BUILDING.md:20-35
Build and Synchronization Workflow
The architecture relies on a synchronization workflow that transfers web assets from the dist directory into native platform projects.
Mobile Build Process Flow
This diagram illustrates the progression from web source code to a native mobile binary.
A brief explanation: The process begins with a standard Vite build, followed by a Capacitor sync command that updates native project dependencies and web assets.
Sources: BUILDING.md:57-85, package.json:14-17
Configuration Management
Mobile-specific configuration and assets are managed through dedicated CLI tools and configuration files.
- Asset Generation: The
@capacitor/assetstool generates icons and splash screens. It requires a sourceresources/icon.png(1024x1024) and uses specific background colors (e.g., black). - Environment Variables: Mobile builds handle sensitive data like
GEMINI_API_KEYby embedding them viacapacitor.config.tsor utilizing secure storage plugins. - iOS Dependencies: The
CapApp-SPMpackage hosts Swift Package Manager (SPM) dependencies required for the iOS target.
Sources: BUILDING.md:65-68, BUILDING.md:95-98, package.json:30, ios/App/CapApp-SPM/README.md
Native Bridge and Web Environment
The mobile application runs within a web view configured for high performance and mobile-specific display characteristics.
Web Manifest and Viewport
The entry point index.html includes meta tags to optimize the mobile experience:
viewport: Configures scale and prevents user scaling for a native feel.apple-mobile-web-app-capable: Enables full-screen mode on iOS.theme-color: Sets the system UI color to match the application's zinc-950 theme.
Sources: index.html:5-10
Native Command Mapping
Mobile lifecycle and development commands are mapped to npm scripts in package.json.
{
"cap:sync": "npm run build && cap sync",
"cap:android": "npm run build && cap sync && cap open android",
"cap:ios": "npm run build && cap sync && cap open ios",
"cap:icons": "npx @capacitor/assets generate --iconBackgroundColor black ..."
}
Sources: package.json:14-17
Sync Cluster Integration
Mobile nodes participate in the "Sync Cluster" to maintain state parity with desktop instances.
Cluster Connectivity Sequence
This sequence describes how a mobile device joins the secure synchronization cluster.
A brief explanation: The mobile device encrypts local data using a symmetric key before syncing with the cluster, ensuring no plain-text data reaches cloud nodes.
Sources: src/components/SyncCluster.tsx:42-55, src/utils/ai.ts:168-175
Technical Constraints and Emulation
Mobile environments face unique constraints regarding local network access.
- CORS Restrictions: Mobile browsers/webviews cannot access local processes (like a local Ollama instance) without proper CORS headers (
OLLAMA_ORIGINS="*") or specialized network configurations. - Workspace Emulator: When direct connections to local LLM providers (Ollama/LM Studio) fail or time out (3500ms), the system falls back to a high-fidelity workspace simulator to maintain functionality.
Sources: src/utils/ai.ts:32-60, src/data.ts:250-255
Summary
The Capacitor-based mobile architecture enables Agent Studio to deploy as a native application on Android and iOS. It utilizes a shared Vite build process, native asset generation, and a secure Sync Cluster to provide a consistent developer experience across desktop and mobile devices. Management of local provider connectivity and mobile-specific configurations is handled through the Capacitor CLI and the internal workspace emulator.