# Plexus setup guide for coding agents

You are a coding agent inside a user's project, asked to wire it up to
[Plexus](https://plexus.company) — telemetry ingestion plus dashboards,
alerts, and fleet operations in the Plexus app. Follow these steps in order.
Anything that changes the user's code or sends data should be shown to them
before you do it.

## 1. Install the SDK

- **Python** (scripts, services, edge devices, Raspberry Pi, gateways):
  `pip install plexus-python`
- **Any other language**: skip the SDK and POST directly to the ingest
  endpoint over plain HTTP (see step 5).

The SDK is a thin ingest client — batching, retry/backoff, and offline
buffering are built in. The browser is not a supported ingest surface; from
web apps, send from server code (API routes, server actions).

## 2. Decide what to track — and confirm it

Read the codebase. Propose **5–10 metrics and events** worth tracking, show
the user the list, and wait for their confirmation before instrumenting.

- **Metrics** are things you measure on a cadence: request latency, queue
  depth, job duration, battery voltage, motor temperature.
- **Events** are things that happen: faults, state transitions, job
  completions/failures, deploys, e-stops.
- Prefer a few load-bearing signals over blanket coverage.
- **Never send secrets, credentials, tokens, or PII as metric values or tags.**

## 3. Get an API key (device-code claim flow)

No key exists yet — you request one and the user approves it in their browser.

1. `POST https://app.plexus.company/api/auth/claim` with JSON body
   `{"name": "<project-name>"}` (the name labels the key in their workspace).
   Response:

   ```json
   {
     "device_code": "…64 hex chars — secret, for your polling only…",
     "user_code": "ABCD-EFGH",
     "verification_url": "https://app.plexus.company/claim/ABCD-EFGH",
     "expires_in": 900,
     "interval": 5
   }
   ```

2. Show the user the `verification_url` and ask them to open it while signed
   in to Plexus (workspace admins/editors can approve). Never show them the
   `device_code`.
3. Poll `GET https://app.plexus.company/api/auth/claim/{device_code}` every
   `interval` seconds:
   - `{"status": "pending"}` — keep polling.
   - `{"status": "approved", "api_key": "plx_…"}` — **delivered exactly
     once**; store it immediately (step 4). It cannot be retrieved again.
   - `{"status": "denied"}` or `{"status": "expired"}` — stop; ask the user
     before starting a new claim.

Claimed keys are issued with **write scope** and are intended as ingest
credentials — treat them as write-only and don't use them for reads or
workspace changes.

## 4. Store the key

- Write it to the project's env file (`.env`, `.env.local`, or equivalent) as
  `PLEXUS_API_KEY=plx_…` — the SDK reads that variable automatically.
- Add `PLEXUS_API_KEY=` (no value) to `.env.example` if the project has one.
- Ensure the env file is gitignored. **Never commit the key or paste it into
  code.**

## 5. Instrument

**Python:**

```python
from plexus import Plexus

px = Plexus(source_id="rig-01")   # reads PLEXUS_API_KEY from env

px.send("engine.rpm", 3450)
px.send_batch([("temperature", 22.4), ("humidity", 58.1)])
px.event("fault", "E-stop triggered")
```

**Any other language (plain HTTP):** POST JSON to the ingest endpoint —
anything with an HTTP client works.

```bash
curl -X POST https://gateway.plexus.company/ingest \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PLEXUS_API_KEY" \
  -d '{
    "source_id": "checkout-api",
    "points": [
      { "metric": "request_latency_ms", "value": 42 }
    ]
  }'
```

Full HTTP reference: https://docs.plexus.company/hardware/http

Rules:

- `source_id` namespaces everything from this app. Use a short
  kebab-case name for the project (`my-next-app`, `packing-robot-01`).
  Lowercase letters, digits, dots, hyphens, underscores; must not look like a
  UUID. One source per deployable thing.
- Metric names are dot- or underscore-namespaced strings (`db.query_ms`,
  `request_latency_ms`). Numbers become time-series; strings/objects become
  events.
- Don't set timestamps yourself unless replaying historical data — the SDK
  stamps points correctly.
- Instrument at the boundaries you proposed in step 2; don't scatter sends
  through every function.

## 6. Verify and hand off

1. Run the app (or a small script) so at least one real point ships.
2. Tell the user their data is live and their dashboard is ready at:
   `https://app.plexus.company/dashboards?quick=<source_id>`
   — that link opens a dashboard builder pre-filled from the metrics you
   actually sent.

Full SDK reference: https://docs.plexus.company