labrat-lab 0.3.0

A universal interface for lab automation

Let the rat run the maze.

Control oscilloscopes, signal generators, VNAs, spectrum analysers, power supplies, cameras and more through one API.

Quick start · Install · API · MCP · Drivers · Contributing

Quick start

pipx install git+https://github.com/reinhardjvv/labrat.git
labrat demo                       # start a demo lab with simulated instruments

In a second terminal, with the token the demo prints:

export LABRAT_URL=http://127.0.0.1:8780 LABRAT_TOKEN=<token>
labrat describe psu
labrat shell                      # an interactive prompt with tab completion

Connect Claude, or any MCP client, to the same lab:

claude mcp add labrat -e LABRAT_URL=$LABRAT_URL -e LABRAT_TOKEN=$LABRAT_TOKEN -- labrat mcp

Every client sends the same message, so curl works too:

curl -s $LABRAT_URL/api/v1/message -H "Authorization: Bearer $LABRAT_TOKEN" \
     -d '{"op": "set", "device": "psu", "name": "VoltageLevel", "channel": "1", "value": 5}'

Ask your agent

With LABRAT connected over MCP, Claude or another agent works the bench the way a person would:

Start an experiment called filter-check. Sweep the generator from 1 to 20 MHz in 1 MHz steps, take a scope
trace at each step, and tell me where the response is 3 dB down.

The agent finds the instruments, locks them, opens an experiment in your folder, runs the sweep and reads its own data back. The lab's limits, locks and approvals apply to every request, and every command is logged under the agent's token. Give it as much freedom as you want (MCP).

The nest and the rats

A lab has one nest and any number of rats. The nest is the server everyone talks to. It holds the tokens, the limits, the locks and the audit log. The rats sit at the benches next to the equipment, and each one serves whatever is plugged into it. A rat can be any Linux computer, from a single-board computer to the PC already beside an instrument, or a microcontroller that speaks the rat protocol. A small lab can run the nest alone, with its devices plugged straight in.

flowchart TB
    clients["<b>clients</b><br/>Python · MATLAB · curl"] -- HTTP --> nest
    agents["<b>AI agents</b><br/>Claude and others"] -- MCP --> nest
    nest["<b>nest</b><br/>central server"]
    nest --> rat1["<b>rat</b> · bench PC<br/>scopes · supplies"]
    nest --> rat2["<b>rat</b> · Raspberry Pi<br/>cameras · SLMs"]
    nest --> rat3["<b>rat</b> · ESP32<br/>relays · sensors"]
    nest --> store[("<b>storage</b><br/>NAS or disk")]

What it works with

A bench instrument needs no code. Its commands go in a few lines of configuration (drivers), and simulated devices let you try everything without hardware.

Use it from

Set up a lab

Any 64-bit Linux runs a nest or a rat. Good defaults are Ubuntu Server LTS or Debian for the nest, and Raspberry Pi OS Lite (64-bit), DietPi or Armbian for rats on single-board computers (which computer and which OS).

Questions

Does it replace PyVISA, LabVIEW or my scripts? No. LABRAT sits between them and the equipment, so every script, notebook and agent sees the same instruments through the same limits and locks. LabVIEW and MATLAB talk to it over HTTP.

Do I need a Raspberry Pi? No. A small lab runs the nest alone on one computer, with its instruments on the network or plugged in. Rats are for equipment that is spread over benches or needs local USB, GPIO or I2C.

What about a device nobody supports? Plug it in and run labrat probe, or ask your agent to work it out. LABRAT asks it safe questions, records what its vendor software says to it, and turns that into a profile, a short file that makes it a normal device. The next lab with the same model gets it from the catalog (catalog).

Is it safe to let an agent drive real equipment? The guardrails are yours to set: limits on every setting, locks, requests that wait for a person, and one stop that puts the whole lab in its safe state. A rat that loses the nest does the same by itself.

Is there a web dashboard? Not yet. The terminal, the Python client and MCP cover everything today, and a dashboard will use the same API.

Can two people use the same instrument? Not at the same time, if they lock it. labrat lock makes a device yours until you let go, labrat who shows who holds what, and require_lock makes a lock necessary before any change. People are added with labrat user add, with no restart.

Where does my data go? Wherever you point it: a local disk or a NAS, in a folder per person and experiment (experiments).

Documentation

Contributing

Drivers, client libraries, documentation and bug reports are all welcome. CONTRIBUTING.md explains the workflow and the house rules. A maintainer reviews every pull request, with an automated review as advice on branches of this repository. Report security issues privately, as SECURITY.md describes.

Licence

LABRAT is released under the Apache License 2.0.