Harness Setup Guide

Agents act through three kinds of doorway. The harness puts one policy and one evidence trail across all of them, so you do not need a different tool per doorway.

Whatever the doorway, every call runs the same ladder: protected paths, workspace confinement, private-network checks, server and tool rules, argument rules, rate limits, on-device DLP on both arguments and results, prompt-injection taint, and administrator approval holds. Blocked calls are answered with a policy error and coaching so the agent explains itself to the user instead of failing mysteriously.

• Node 20 or newer on the machine. Check with node --version.
• An org enrollment key. Create one in the dashboard under Settings → API access. It is used only to enroll; every machine then mints its own endpoint key.
• A free seat. Each machine is one endpoint against your plan's endpoint limit, the same as a browser.
• A policy worth enforcing. Not required to install, but the harness enforces what your org policy says, so review the Tools and Models tabs before rolling out widely.

Three lines onboard a whole machine.

npm install -g @medusasec/harness

medusa setup --org-key sk-med_your_key_here --profile

medusa doctor

setup is the whole flow. --profile also adds the model environment to your shell profile so CLI agents route through the proxy. Add --dry-run first if you want to see exactly what it would change without touching anything.

What you should see

Medusa Harness 0.1.0 — setup

  ✓ enroll: enrolled as hx:cb023e8d-9736-493a-a10d-365fe0e0db9e
  ✓ policy: synced (verified) etag W/858bea63-…
  ✓ wrap:claude_code: wrapped github, filesystem
  ✓ wrap:cursor: wrapped postgres
  ✓ model-env: wrote ~/.medusa/harness/env.sh and added it to ~/.zshrc
  ✓ service: launchd agent loaded (starts at login, restarts on crash)
  ✓ doctor: all checks passed

Next:
  → Restart your MCP clients so they pick up the wrapped servers.
  → Watch the traffic on the dashboard: Tool calls, Harness endpoints, Compliance.

Each step is something you can also run on its own if you prefer to wire seams by hand.

1. Health check

medusa doctor

Checks enrollment, key permissions, policy freshness and signature, control-plane reachability, spool health, and which clients are wrapped. Exits non-zero if anything needs attention, so it works as an MDM health probe. Add --json for machine-readable output.

2. Prove a block from a shell

medusa check --tool write_file --args '{"path":"~/.cursor/mcp.json","content":"{}"}'
# → block · protected_path_tamper

medusa check --tool echo --args '{"text":"AKIAIOSFODNN7EXAMPLE"}' --record
# → coach · dlp_detection  (and, with --record, a real receipt)

check runs the real gate without needing an agent. Without --record nothing is written; with it, the call is spooled and receipted exactly like a live one.

3. Confirm on the dashboard

• Tool calls — every gated call with its verdict and receipt, within seconds.
• Harness — the machine, its version, policy state and the tool servers it exposes.
• Compliance — the endpoint against the five fleet controls.
• Receipts — verify the chain against the pinned key.

setup wires all of these. This section is for when you want to configure one deliberately, or understand what a given seam does.

MCP tools launched by a client (stdio)

medusa clients                       # what is configured and what is wrapped
medusa install --client all --dry-run
medusa install --client all          # or --client claude_code | cursor | claude_desktop | windsurf | vscode
medusa install --path ./.mcp.json    # a project-level config

A wrapped entry becomes node …/medusa proxy --server github -- npx -y @modelcontextprotocol/server-github. Every JSON-RPC frame in both directions passes the gate: allowed frames forward untouched, results with sensitive data are redacted before the agent sees them, and blocks answer with JSON-RPC error -32001 plus coaching. Entries from the retired Python agent are migrated automatically.

MCP tools over HTTP or SSE

medusa serve            # loopback proxy on 127.0.0.1:27182 (the background service runs this for you)

URL-based servers are rewritten to http://127.0.0.1:27182/proxy/<name> and the real URL, with any static headers, moves to the routes file. Streamable HTTP and SSE are relayed event by event with each message gated, and one session is kept across the handshake so client identity, taint and receipt continuity survive.

Model APIs from CLIs and SDKs

medusa env               # show the variables
medusa env --export      # a sourceable script
source ~/.medusa/harness/env.sh

Points the SDK base URLs at 127.0.0.1:27183. The proxy checks allowed models, enabled providers and the daily token or spend budget, scans the prompt with your detectors before it leaves the machine, forwards to the real provider, optionally scans the response, and signs a receipt. OpenAI chat/completions and responses, Anthropic messages and Google generateContent shapes are all understood; streaming passes through.

Agents you write yourself

import { createHarness } from "@medusasec/harness";

const harness = createHarness({ server: "my-agent", client: { name: "my-agent", version: "1.0" } });

// Gate your tools — blocked calls throw with err.medusa.rule and coaching.
const tools = harness.wrap({
  readFile: { name: "read_file", run: async ({ path }) => fs.readFileSync(path, "utf8") },
});
await tools.readFile({ path: "/tmp/notes.txt" });

// Gate a model request before you send it (returns possibly-redacted messages).
const { messages } = harness.llm({ provider: "openai", model: "gpt-4o", messages: prompt });

// Feed untrusted content in so injection taints the session.
harness.observeContent(fetchedPage, "web");

The MCP tool traffic of a GUI app is already covered by the config wrapping above, because the app reads the same mcp.json whether it is a GUI or a CLI. The one remaining gap is the direct model API call a GUI app makes, because those apps ignore shell environment. Cursor routes only its chat panel through a custom base URL, never autocomplete or inline edit; Claude Desktop and the ChatGPT app expose no base-URL setting at all.

Closing that gap takes a local HTTPS proxy plus two administrator decisions.

medusa capture           # starts the proxy and prints everything below
medusa ca trust          # prints the exact command to trust the harness CA
medusa ca fingerprint    # SHA-256 of the CA, to verify what you are trusting

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain ~/.medusa/harness/ca/medusa-ca.crt

certutil -addstore -f Root %USERPROFILE%\.medusa\harness\ca\medusa-ca.crt

sudo networksetup -setsecurewebproxy "Wi-Fi" 127.0.0.1 27184

reg add "HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings" /v ProxyEnable /t REG_DWORD /d 1 /f
reg add "HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings" /v ProxyServer /t REG_SZ /d "https=127.0.0.1:27184" /f
netsh winhttp set proxy 127.0.0.1:27184      # as Administrator, for services and WinHTTP apps

What it does and does not touch

• Inspects only model API hosts — OpenAI, Anthropic, Google, Azure OpenAI and Mistral. Everything else is tunnelled through untouched and never decrypted, so ordinary browsing and app traffic are unaffected.
• Gates identically to every other seam — allowed models, providers, budgets, prompt and response DLP, and a signed llm_request receipt tagged to the harness/egress seam.
• Apps that pin certificates will refuse it. That is the app defending itself and is expected; those calls fail rather than being silently downgraded. If a critical app pins, leave the proxy off for that host.
• HTTP/1.1 only, and one request per tunnel — clients reconnect transparently, at a small efficiency cost.

A coding agent's own tools are not MCP. Claude Code's Bash, Edit, Write, Read and WebFetch, and Cursor's shell commands, file reads and file edits, never pass through an MCP config, so config wrapping cannot see them. Both agents expose hooks for exactly this, and medusa setup wires the harness into them: every native tool call runs through the same gate as an MCP call, with the same policy, taint tracking and signed receipts.

medusa hooks            # status per agent
medusa hooks install    # wire Claude Code (~/.claude/settings.json) and Cursor (~/.cursor/hooks.json)
medusa hooks managed    # print the organization-wide files an MDM ships so users cannot remove them

For a fleet, medusa hooks managed prints Claude Code's managed-settings.json with allowManagedHooksOnly and Cursor's enterprise hooks.json, with the paths for macOS, Linux and Windows. Ship those from your MDM and a user cannot switch the hooks off. The hook files themselves are protected paths, so an agent cannot edit them either.

Claude Enterprise organizations can route every governed prompt in claude.ai, Cowork and Claude Code through an Inference hook: Anthropic sends the transcript to a security server before inference and waits for allow or deny. This control plane is that server. It covers people who use Claude without the harness or the extension installed, and it applies to the desktop, web and mobile apps alike.

1. Settings → Claude Enterprise inference hook → Create endpoint, copy the URL.
2. Anthropic console → Organization settings → Inference hooks: paste the URL, run Test connection, copy the signing secret it generates.
3. Paste the secret back into Medusa, enable the hook, leave shadow mode on, and watch the Tool calls page under the “Claude Enterprise (cloud)” doorway.
4. Turn shadow mode off when the verdicts look right. Anthropic's own rollout percentage and role exclusions still apply.

No Enterprise organization to test with? node scripts/inference-hook-simulate.mjs <endpoint-url> --secret whsec_… --case tool-secret in the control-plane repository sends a frame signed exactly the way Anthropic signs it (cases: clean, secret, tool-secret, injection, config-test) and prints the verdict, so the whole path can be exercised and demonstrated.

The harness enforces what your org policy says. Both blocks live in the policy editor on the Policy page, and scope, groups, versioning and signing work exactly as they do for browsers.

Roll out safely with observe mode

Turn on Observe onlyin the Tools tab first. Every verdict is recorded as “would have blocked” without actually blocking, so you can watch Tool calls for a few days and tune rules before enforcing. Protected-path tampering is still blocked in observe mode, by design.

One unattended command per machine, run as the user, from Jamf, Intune, Kandji or any config manager.

MEDUSA_ORG_KEY=sk-med_your_key_here \
MEDUSA_UNATTENDED=1 \
MEDUSA_USER_EMAIL="$USER@yourcompany.com" \
  npx -y @medusasec/harness setup --json

--json prints a structured report and exits non-zero if any step failed, so your MDM can report success or failure per machine. Re-running setup is safe: it reuses an existing enrollment and only wraps what is not already wrapped.

For GUI coverage, add the CA and proxy payloads described in GUI apps to the same MDM profile.

medusa doctor            # full health check (use --json in monitoring)
medusa status            # enrollment, receipts issued, spool depth
medusa receipts --verify # verify the local receipt ledger (hashes, links, signatures) on this machine
medusa policy            # re-sync and print what is enforced
medusa budget            # today's model token and spend usage
medusa service status    # is the background service installed and running
medusa clients           # which MCP clients are wrapped

The background service logs to ~/.medusa/harness/run.log. Events are written to a durable spool before delivery and only trimmed once the control plane acknowledges them, so a laptop that goes offline keeps enforcing and backfills its receipts when it reconnects. Receipts are never dropped, even under the spool size cap.

Upgrades are an npm install away: npm install -g @medusasec/harness then medusa setup again to re-wrap anything new. The Compliance page flags machines running an outdated harness.

medusa uninstall --client all    # restores every original MCP config from backup
medusa service uninstall         # removes the background service
npm uninstall -g @medusasec/harness

If you enabled the GUI proxy, also remove the system proxy setting and delete the trusted CA from the keychain or trust store. Finally, remove the endpoint from the Harness page to revoke its key — its receipts stay for your retention window, so evidence is not lost when a machine leaves the fleet.

Every gated action produces an event and, for tool and model calls, a signed receipt in a hash-chained sequence. A receipt records the endpoint, session, action, upstream server or model, the verdict and the rule that fired, the agent and OS user, and category counts.

What is never sent

• Prompt text, file contents and tool arguments stay on the machine.
• Detected values are never transmitted in full. Events carry a category count and a short truncated preview, so a secret that triggered a block does not itself become a leak in your logs.
• Traffic to hosts outside the model allowlist is never decrypted by the egress proxy.

Receipts are signed on the machine with a key that never leaves it, and every one is also kept in a local append-only ledger (~/.medusa/harness/receipts.jsonl, owner-only) so the chain can be verified on the endpoint itself, offline, without trusting the control plane. medusa receipts lists it; medusa receipts --verify recomputes every hash, link and ES256 signature against the pinned key and exits non-zero on any problem, which is what an on-site auditor runs. The control plane pins the first key it sees, verifies chains nightly, and can produce an attestation over any range — the basis of the evidence pack, which maps each artifact to SOC 2, NIST AI RMF, ISO 42001, EU AI Act and CIRCIA controls.