Open app

Quickstart

By the end of this page you'll have something sending readings to Plexus and a dashboard, built for you, showing them. There are two ways in:

With a coding agent

In Claude Code, run this in your project's terminal:

claude mcp add --transport http plexus https://app.plexus.company/mcp

In Cursor, Codex or another agent, add https://app.plexus.company/mcp as an MCP server.

Then tell the agent:

set up Plexus

Your browser opens once. Sign in, or create an account, and approve. The agent then:

  1. creates an API key that can only send data, and saves it as PLEXUS_API_KEY in a git-ignored env file
  2. adds a few lines to your project that send one real reading, and runs it
  3. gives you the link to the dashboard Plexus built from that reading

After that it offers more readings worth sending, and you choose which to add. You can also ask it to change your dashboards. See Change dashboards with your coding agent.

A project in a language other than Python works too. The agent sends over plain HTTP instead of the SDK.

On a device with no agent

You need Python 3.10 or newer.

1. Create a key. Sign up at app.plexus.company and create a key on the API Keys page. It starts with plx_ and is shown once, so copy it now.

2. Install the SDK and set the key on the device:

pip install plexus-python
export PLEXUS_API_KEY=plx_...

On a Raspberry Pi, recent versions of Raspberry Pi OS block that pip command. Install into a virtual environment instead, and run your script with ~/plexus-venv/bin/python:

python3 -m venv ~/plexus-venv && ~/plexus-venv/bin/pip install plexus-python

3. Send a reading:

from plexus import Plexus

px = Plexus(source_id="my-first-device")   # reads PLEXUS_API_KEY
px.send("temperature_c", 21.5)

source_id names the device. It appears in Plexus the first time it sends.

Open your dashboard

Within a few seconds of the first reading, Plexus builds a dashboard named after the device, such as my-first-device — starter. It is under Dashboards, and if you have Home open it appears there by itself. It is built whether or not you have the app open.

What you should see: a stat tile for each metric you sent, with a trend chart under it.

Plexus picks the layout from the metric names. Names ending in _pct, _c, _ms or _v, or containing temp, voltage or latency, get a stat tile with the right unit. Name your metrics that way and the starter dashboard comes out right the first time.

The dashboard is yours to change: add panels or rename it, in the app or by asking your agent. Sharing it by link and inviting teammates need Pro; on Free the app asks you to upgrade.

Send your own data

Send the readings your hardware produces, such as battery voltage, motor current or signal strength, on a loop:

import time

from plexus import Plexus, PlexusError

px = Plexus(source_id="my-first-device")   # reads PLEXUS_API_KEY

while True:
    try:
        px.send_batch([
            ("battery_v", 12.4),
            ("motor_current_a", 3.1),
            ("signal_dbm", -71),
        ])
    except PlexusError as err:
        # The SDK has saved the points and sends them with the next batch.
        print("send failed, will retry:", err)
    time.sleep(5)

If the network drops, send_batch() retries, saves the points on disk and then raises PlexusError. The try keeps the loop alive, and the saved points go out with the next batch that gets through.

Give every device its own source_id. Two devices sending the same name are merged into one device. For a fleet, build the name from something physically unique, like a serial number, rather than baking one name into a shared image.

Troubleshooting

No dashboard appeared. Plexus builds a starter only for an account with no dashboards yet, from a device's first readings. If you already had a dashboard, or the device sent before, open https://app.plexus.company/devices/my-first-device and click Save as dashboard. You get the same layout.

ValueError about a missing API key. PLEXUS_API_KEY isn't set in the shell or service that runs your script. Set it there, or pass api_key= to Plexus().

AuthenticationError: Invalid API key. The key was mistyped or revoked. Create a new one under API Keys. Copy the whole key, including the plx_ prefix. An org on an older plan whose API access is turned off for billing gets the same error when sending; check Settings → Subscription.

error: externally-managed-environment from pip. Recent Raspberry Pi OS and Debian block system-wide installs. Install into a virtual environment: python3 -m venv ~/plexus-venv && ~/plexus-venv/bin/pip install plexus-python, then run your script with ~/plexus-venv/bin/python.

AuthenticationError: API key doesn't have write permissions. The key can read but not send. Create one with write access under API Keys.

ValueError: Invalid source_id. Source ids are lowercase letters, digits, dots, hyphens and underscores, starting with a letter or digit. My Robot fails; my-robot-01 works.

Readings stopped on a 4th device. The free plan takes 3 devices. Points from a 4th are dropped, and the three you have keep working. See Plans and limits.

Your device sits behind a firewall. The SDK needs outbound HTTPS to gateway.plexus.company.

Read it from the API

Your readings are also available over the read API with the same key:

curl https://api.plexus.company/v1/sources/my-first-device/metrics/latest \
  -H "x-api-key: YOUR_API_KEY"
{ "metrics": { "temperature_c": 21.5 } }

/metrics/latest returns only metrics reported in the last hour. For a live view in your own app, see Live streams.

Next steps