HealthClawGuardrails

Install dependencies

uv sync

Playwright end-to-end tests (UI + API, requires Flask on :5000)

cd e2e && npm ci && npx playwright install --with-deps chromium && npm test cd e2e && npm run test:headed # headed browser cd e2e && npm run test:ui # interactive UI mode ```

Watch the deployment grade its own guardrails (PHI redaction, audit, step-up, ...):

curl "https://app.healthclaw.io/r6/fhir/\$conformance?format=text" ```

Point any MCP client at the public demo server — URL https://mcp-demo-production-ee2c.up.railway.app/mcp, no key required — then ask: "Search my health records for lab results and explain them in plain language." The demo server is unauthenticated but hard-pinned to a synthetic demo tenant, so it can only ever serve fake data. A separate production endpoint (mcp-server-production-5112) requires a deployment-scoped Authorization: Bearer <token> — real records stay behind auth, always. Hosted connectors cannot attach that header, so the demo URL above is the one to paste. One-command installs: gemini extensions install https://github.com/aks129/HealthClawGuardrails · claude plugin marketplace add aks129/HealthClawGuardrails · skills on ClawHub

Non-developer? Step-by-step guides for Claude (web/desktop/phone), Perplexity, ChatGPT, and Telegram — plus a 10-minute demo script — in docs/quickstarts/.

Listed in: Official MCP Registry (io.github.aks129/healthclaw-guardrails) · Glama (hosted connector) · ClawHub (14 skills) · Gemini CLI Extensions · agent-skills discovery at /.well-known/agent-skills/

Install as a Claude Plugin

HealthClaw ships as a Claude Code plugin marketplace. Two plugins are available:

```bash

Install the FHIR guardrail plugin (this repo)

claude plugin install healthclaw-guardrails@healthclaw-marketplace

Install the personal-health companion plugin (frozen — upstream archived)

claude plugin install smarthealthconnect@healthclaw-marketplace ```

Each skill is auto-discoverable — Claude loads it when your prompt matches the skill's trigger phrases (e.g. "check my care gaps", "redact this bundle", "run Curatr on my conditions").

Not on Claude/MCP? The same 28 guardrailed tools run on OpenAI, Gemini, LangChain, or plain HTTP via the framework-neutral bridge in adapters/ — see Recipe: run HealthClaw tools on any agent framework. Guardrails stay server-side, so no framework can bypass them.

Docker

```bash docker-compose up -d --build

HOST_PORT=5050 docker-compose up -d --build

Railway Deploy

```bash

5. Deploy — MUST run from the shl-server directory

cd services/shl-server && railway up --service shl-server

Quick Start

```bash

Quick Start (local)

```bash

Guardrail Demo

The 6-step demo at /r6/fhir/demo/agent-loop shows the full guardrail sequence:

1. PHI Redaction — Agent reads a patient, receives redacted data
2. $validate Gate — Agent proposes an Observation, validated before write
3. Permission Deny — No Permission rule exists, access denied with reasoning
4. Permission Permit — Permit rule created, re-evaluation succeeds
5. Step-up + Human-in-the-loop — Write requires both token and human confirmation
6. Commit + Audit — Write succeeds, full audit trail generated

Add to services/agent-orchestrator/.env or export:

export SHL_SERVER_URL=http://localhost:8000 ```

Without SHL_SERVER_URL, shl_generate returns an explicit simulation stub (simulated: true) — never a fake link.

3. Configure the SHL server

railway variables --service shl-server \ --set BASE_URL=<public-url-of-shl-server> \ --set DB_PATH=/data/db.sqlite

Environment Variables

Database DDL is never run during WSGI import. Run flask --app main init-db before each release; it applies the locked Alembic revisions. Operators adopting Alembic on an existing v1.8.0 Postgres deployment must follow the database migration runbook to verify and stamp the compatibility baseline before upgrading.

4. Set up Fasten Connect (optional)

```bash

.env additions

FASTEN_PUBLIC_KEY=<key> FASTEN_PRIVATE_KEY=<key> FASTEN_WEBHOOK_SECRET=<secret> FASTEN_CURATR_SCAN=true # auto-run Curatr after each import ```

Records arrive via webhook at /r6/fasten/webhook and are stored under the patient's canonical tenant ID.

6. Telegram bot (optional)

TELEGRAM_BOT_TOKEN=<token> TENANT_ID=my-patient \
FHIR_BASE_URL=http://localhost:5000/r6/fhir \
python openclaw/bot.py

Commands: /health, /conditions, /labs, /curatr, /curatr fix, /approve.

Or via Docker Compose:

docker-compose --profile openclaw up -d

7. Use Medplum as the backing FHIR store (optional)

Set in .env (leave FHIR_UPSTREAM_URL empty):

MEDPLUM_BASE_URL=https://api.medplum.com/fhir/R4
MEDPLUM_CLIENT_ID=<id>
MEDPLUM_CLIENT_SECRET=<secret>

All guardrails apply to Medplum responses identically to local SQLite mode. Access tokens are cached in Redis (key medplum:access_token; falls back to in-process cache when Redis is unavailable).

---

API Endpoints

Local search accepts the parameters advertised by /r6/fhir/metadata. Unknown parameters default to lenient handling (a bounded search.mode="outcome" warning); Prefer: handling=strict returns a 400 OperationOutcome. Unsupported modifiers and malformed supported values always return 400. _count=0 and _summary=count are count-only searches. Self links contain exactly the applied, URL-encoded parameters, and audit output never echoes submitted filter values or arbitrary parameter names.

Comparison