# 3pm-backend

The fleet backend of [3pm](https://github.com/Unitech/3pm): the server
side of `3pm link`. It enrolls hosts into buckets, admits their agents
over one WebSocket each, ingests the redacted process table and host
metrics at 1 Hz, and serves a JSON API, an SSE feed and a small
dashboard. axum 0.8 + SQLite, one binary, no other service.

```
$ just dev          # --dev on 127.0.0.1:9616, clear text, local advertise allowed
```

Open `http://127.0.0.1:9616/`, create a bucket, mint a token, and paste
the printed line on a host running 3pm:

```
$ 3pm link 3pmc_<cluster> 3pmk_<token> ws://127.0.0.1:9616
```

## Building

This repository builds next to a checkout of 3pm: the shared crates
(`threepm-link`, the wire contract; `threepm-core`, `threepm-protocol`;
`threepm-testsupport` for the real-agent test) are path dependencies on
`../3pm/crates/…`.

```
3pm-rd/
  3pm/            git clone https://github.com/Unitech/3pm
  3pm-backend/    this repository
```

| Recipe | What it runs |
|---|---|
| `just check` | `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings` |
| `just test [filter]` | unit + integration tests under `cargo nextest`; the integration tests are one binary, `tests/it`, a module per file (`just test 'test(/^auth_e2e::/)'` runs one) |
| `just e2e` | builds a debug `3pm` and its `agent` module from `../3pm`, then the `real_agent*` modules of `tests/it` |
| `just dev` | the backend in `--dev` mode on `127.0.0.1:9616` |
| `just msrv` | `cargo +1.88 check` |
| `just ci` | everything CI gates |

`THREEPM_SRC=/path/to/3pm just e2e` uses another checkout for the
binaries (the path dependencies stay on `../3pm`).

## Documentation

- [FEATURES.md](FEATURES.md): what the backend does, one section per
  user-facing feature.
- The wire contract, the shared crate and the agent module are
  documented in 3pm under `docs/backend-agent/`.

`docs/backend.md` — configuration, HTTP API and SSE feed, enrollment and
link endpoints, the hub, database, crypto, file by file, tests, caveats —
left the tree on 2026-09-09 and lives in OpenViking at
`viking://resources/3pm-backend-docs-archived/backend/`. The section names
quoted across this repository ("→ Metrics store", "→ Metrics API") are its.