Introduction

What is a Device Agent?

A device agent is a small program that runs on your computer (Mac, Windows, Linux, or mobile devices) to connect it to Sulala.ai. Think of it as a "bridge" between your local device and the cloud service.

Why Do You Need It?

To test the Sulala application, your device needs to:

1. Stay connected to Sulala.ai (send "I'm online" messages)
2. Receive search requests from the cloud
3. Search your local files when requested
4. Send results back to the cloud
5. Handle file uploads when needed

Without the agent, your device can't communicate with Sulala.ai, and you won't be able to test the application's device integration features.

What Does It Do?

The device agent performs the following functions:

• ✅ Connects to Sulala.ai every 30 seconds via heartbeat
• ✅ Checks for pending search requests from the cloud
• ✅ Executes searches on your local files, apps, and system information
• ✅ Sends results back to the cloud automatically
• ✅ Handles file upload requests when files need to be synced
• ✅ Keeps your device status as "online" in the dashboard

Two Ways to Test

Sulala provides two device agent implementations for developers:

1. JavaScript/Node.js Agent

2. Flutter Agent

How It Works

The device agent follows this workflow:

1. User starts the agent with an API key
2. Agent connects to Sulala.ai cloud service
3. Sends heartbeat every 30 seconds to maintain connection
4. Polls for search requests from the cloud
5. Executes searches locally (files, apps, system info)
6. Sends results back automatically
7. Handles file upload requests when needed

All of this happens automatically - you don't need to do anything after starting the agent!

Prerequisites

Before you begin, make sure you have:

• API Key: Get your device API key from the Sulala dashboard (Dashboard → Devices → Your Device → API Key)
• Server URL: The URL of your Sulala instance (default: http://localhost:3000 for local development, or your production URL)
• Development Environment:
  • For JavaScript agent: Node.js 18+ and npm
  • For Flutter agent: Flutter SDK 3.9.2+

Next Steps

Choose your preferred agent implementation:

• JavaScript/Node.js Agent Guide - For desktop testing with Electron
• Flutter Agent Guide - For cross-platform testing including mobile