The Flutter device agent is a cross-platform application that connects your device to Sulala.ai. It's a Flutter rewrite of the Electron-based device agent, providing better platform support including mobile devices (Android and iOS).
✅ Cross-platform - Works on Windows, macOS, Linux, Android, and iOS
✅ Simple GUI - No command line needed
✅ One-click start - Just enter API key and click start
✅ System tray - Runs in background (desktop platforms)
✅ Auto-reconnect - Automatically reconnects if connection drops
✅ Status indicator - See connection status at a glance
✅ Local search - Searches files, apps, and system info
✅ File upload - Uploads files to cloud storage
For desktop builds:
For mobile builds:
cd sulala_device_agent
flutter pub get
# For your current platform
flutter run
# For specific platforms
flutter run -d windows
flutter run -d macos
flutter run -d linux
flutter run -d android
flutter run -d ios
http://localhost:3000, change to your production URL)The app runs in the background. On desktop platforms, you can minimize it to the system tray.
# macOS
flutter build macos
# Windows
flutter build windows
# Linux
flutter build linux
# Android
flutter build apk --release
# or for app bundle
flutter build appbundle --release
# iOS
flutter build ios --release
You can set the server URL at build time:
flutter build macos --dart-define=SERVER_URL=https://sulala.ai
Or set it at runtime using an environment variable:
# macOS/Linux
export SULALA_SERVER_URL=https://sulala.ai
flutter run
# Windows
set SULALA_SERVER_URL=https://sulala.ai
flutter run
The Flutter agent:
All automatic - user doesn't need to do anything after starting!
lib/
├── main.dart # App entry point
├── screens/
│ ├── home_screen.dart # Main UI screen
│ └── qr_scanner_screen.dart # QR code scanner
├── services/
│ ├── agent_service.dart # Core agent logic (heartbeat, polling, uploads)
│ ├── notification_service.dart # Local notifications
│ └── tray_service.dart # System tray integration
├── platform/
│ └── search_service.dart # Platform-specific search functions
└── config/
└── app_config.dart # App configuration
Singleton service managing the agent lifecycle:
Platform-specific implementations for searching:
/Applications and ~/ApplicationsProgram Files directories/usr/bin, /usr/local/bin, /optSystem tray integration for desktop platforms:
The agent communicates with the following Sulala.ai endpoints:
POST /api/devices/heartbeat - Send device heartbeatGET /api/devices/search/pending - Poll for search requestsPOST /api/devices/search - Submit search resultsGET /api/devices/files/upload-requests/pending - Poll for upload requestsPOST /api/devices/files/upload - Upload file to cloudSettings are stored locally using shared_preferences:
These are automatically saved when you start the agent.
The server URL can be configured in three ways (in order of precedence):
SULALA_SERVER_URL--dart-define=SERVER_URL=...https://sulala.aiflutter doctorflutter pub get to install dependenciesflutter doctor to check for issuesflutter run --debug
flutter test
flutter format lib/
During development, you can use hot reload:
r in the terminal to hot reloadR to hot restartq to quit/Applications and ~/Applications