swarm-client Setup

swarm-client connects your lab's physical devices to Swarm Cloud, enabling AI and API control.

Overview

swarm-client is open-source software that runs on a computer in your lab. It:

• Connects to your devices via USB, serial, or network
• Maintains a secure WebSocket connection to Swarm Cloud
• Executes commands from Claude or the REST API
• Reports device status back to the cloud

Repository: github.com/Cheshire-Labs/swarm-client

Prerequisites

• Python 3.10 or higher
• Computer with access to your lab devices
• Network access to swarm.cheshirelabs.io (outbound HTTPS/WSS)
• API key from Cheshire Labs

Installation

From GitHub

git clone https://github.com/Cheshire-Labs/swarm-client.git
cd swarm-client
pip install -e .

From PyPI (Coming Soon)

pip install swarm-client

Configuration

Create a configuration file (e.g., config.json) anywhere on your system:

{
  "server": {
    "url": "wss://swarm.cheshirelabs.io/ws/devices",
    "api_key": "${SWARM_API_KEY}"
  },
  "devices": [
    {
      "device_id": "my-shaker",
      "type": "shaker",
      "driver": "inheco_thermoshake",
      "config": {
        "port": "COM3"
      }
    }
  ]
}

Environment Variables

You can use environment variables in the config with ${VAR_NAME} syntax:

export SWARM_API_KEY=your-api-key-here

Device Configuration

Each device entry requires:

Field	Description	Example
device_id	Unique identifier for this device	"lab1-shaker-01"
type	Device type	"shaker", "centrifuge", "sealer", "transporter"
driver	Driver to use	"inheco_thermoshake", "preciseflex"
config	Driver-specific settings	Port, IP address, etc.

Example Configurations

Shaker (USB/Serial):

{
  "device_id": "plate-shaker",
  "type": "shaker",
  "driver": "inheco_thermoshake",
  "config": {
    "port": "COM3"
  }
}

Transporter (Network):

{
  "device_id": "robot-arm",
  "type": "transporter",
  "driver": "preciseflex",
  "config": {
    "host": "192.168.1.100",
    "port": 10100
  }
}

Running swarm-client

Pass the path to your config file:

swarm-client --config /path/to/config.json

On startup, swarm-client will:

1. Load your configuration
2. Connect to each device
3. Establish a WebSocket connection to Swarm Cloud
4. Register your devices

You should see output like:

Connecting to wss://swarm.cheshirelabs.io/ws/devices...
Connected to Swarm Cloud
Registering device: my-shaker (shaker)
Device my-shaker registered successfully
Ready for commands

Verifying Connection

Once swarm-client is running, verify from Claude or the API:

With Claude:

"What devices are connected to Swarm AI?"

With REST API:

curl -H "X-API-Key: your-api-key" \
  https://swarm.cheshirelabs.io/api/devices

Your devices should appear in the list.

Running as a Service

For production use, run swarm-client as a system service so it starts automatically and restarts on failure.

Linux (systemd)

Create /etc/systemd/system/swarm-client.service:

[Unit]
Description=Swarm Client
After=network.target

[Service]
Type=simple
User=labuser
WorkingDirectory=/home/labuser/swarm-client
Environment=SWARM_API_KEY=your-api-key
ExecStart=/home/labuser/.venv/bin/swarm-client --config /home/labuser/swarm-client/config.json
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable swarm-client
sudo systemctl start swarm-client

Windows

Use Task Scheduler or a Windows service wrapper like NSSM to run swarm-client at startup.

What's Next?

• Claude Desktop Setup - Connect Claude Desktop
• Devices Overview - Supported device types
• Troubleshooting - Common issues