Check your deployment
Measure your deployment's speed against targets with one command.
pistis doctor runs test sessions against your deployment and checks how fast each step is. It exits 0 when every target is met, so you can run it after every change.
Before you start
- An API token for any person (API tokens)
- A shell inside the deployment's network, because Pistis servers never publish their metrics
- A quiet moment: other traffic during the run counts too
Run it
# compose
docker compose exec brain1 node packages/pistis/src/main.ts doctor \
--url http://brain1:8787 --token $PISTIS_TOKEN \
--metrics http://brain1:9464/metrics --metrics http://brain2:9464/metrics \
--json /tmp/doctor.json
# Kubernetes
kubectl exec pistis-brain-0 -- node packages/pistis/src/main.ts doctor \
--url http://pistis --token $PISTIS_TOKEN \
--metrics http://pistis-brain-0.pistis-brains:9464/metrics \
--metrics http://pistis-brain-1.pistis-brains:9464/metricsThe check's sessions use a small offline model built into Pistis, so they need no model key and cost nothing. Doctor ends every session it started.
What it checks
| Check | What it times | Target (p95) |
|---|---|---|
lease-cold | A new sandbox, started and connected | 10 s |
lease-warm | A spare sandbox claimed (skipped without spares) | 0.3 s |
tool-call | A command in a running sandbox, end to end | 0.25 s |
dispatch | Message accepted to model request | 0.25 s |
hands-rtt | One round trip from Pistis to the sandbox | 0.05 s |
hand-over | A message passed to the server handling the session (skipped with one server) | 0.1 s |
Change a target with --target name=seconds. --json writes the results to a file for CI or a dashboard. If a server restarts during the run, doctor asks you to run it again.
A real run
On two servers with Postgres, Docker sandboxes and one spare sandbox each. In the output, a brain is a Pistis server and a box is a sandbox. A command goes from the brain through the relay, which passes messages, to pistisd and pi-env, which run it in the sandbox:
doctor: 2 warm boxes ready; starting 3 sessions at once (one leases cold) lease-cold p95 ≤ 2.5s target 10 s n=2 ok — a new box, booted and connected lease-warm p95 ≤ 0.1s target 0.3 s n=6 ok — a warm box claimed tool-call p95 ≤ 0.025s target 0.25 s n=20 ok — a command in a leased box, end to end dispatch p95 ≤ 0.1s target 0.25 s n=28 ok — message accepted → model request hands-rtt p95 ≤ 0.005s target 0.05 s n=36 ok — one trip brain → relay → pistisd → pi-env hand-over p95 ≤ 0.05s target 0.1 s n=25 ok — a message handed to the brain holding the session doctor: every target met
Check the sandboxes too
- In a session, ask the agent to run
env. The output has no git, model or other keys. - Ask it to run
curl -sS https://example.com. It fails unless you allowed it (Network access). - On Kubernetes, run
kubectl get pod -n pistis-boxes -l app.kubernetes.io/managed-by=pistis -o yaml. It shows no service-account token and no privilege escalation.