The JavaScript/Node.js device agent is an Electron-based desktop application that connects your device to Sulala.ai. It's perfect for desktop development and testing on Windows, macOS, and Linux.
✅ Simple GUI - No command line needed
✅ One-click start - Just enter API key and click start
✅ System tray - Runs in background
✅ Auto-reconnect - Automatically reconnects if connection drops
✅ Status indicator - See connection status at a glance
✅ Cross-platform - Works on Mac, Windows, Linux
The easiest way to test is to run the agent in development mode:
# Navigate to the device-agent directory
cd device-agent
# Install dependencies
npm install
# Start the agent in development mode
npm start
The app will open! Enter your API key and click "Start Agent".
cd device-agent
npm install
This will install all required dependencies including Electron and other Node.js packages.
When you run the app, you'll see a GUI where you can:
http://localhost:3000, change to your production URL if needed)The API key and server URL are automatically saved for future use.
npm start
The Electron app will launch. After entering your API key and clicking "Start Agent", your device will be connected to Sulala.ai.
If you want to build a distributable version of the agent:
# macOS
npm run build:mac
# Windows
npm run build:win
# Linux
npm run build:linux
npm run build
If you want to build without code signing (users will see a warning but it works):
# macOS example
CSC_IDENTITY_AUTO_DISCOVERY=false npm run build:mac
Built apps will be in device-agent/dist/:
.dmg file.exe installer.AppImage fileThe JavaScript agent:
All automatic - user doesn't need to do anything after starting!
device-agent/
├── main.js # Electron main process
├── index.html # UI interface
├── package.json # Dependencies and scripts
├── README.md # Documentation
└── dist/ # Built applications
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 cloudThe agent uses the following configuration:
http://localhost:3000, can be changed in the GUInode --versionnpm install to ensure all dependencies are installeddevice-agent directoryThe agent runs in development mode when you use npm start. You can see console output in the terminal and use Chrome DevTools for debugging.
The agent outputs logs to the console. Watch for:
You can test against different Sulala instances by changing the server URL in the GUI:
http://localhost:3000https://staging.sulala.aihttps://sulala.ai