Build APIs that stay correct after they ship.

1. 1
   Connect the agent

   Run the installer and choose your coding agent.

2. 2
   Restart the agent

   Configuration changes are loaded when the host restarts.

3. 3
   Confirm the workspace

   Ask the agent to run preman_status.

4. 4
   Start with your API

   Discover routes, test them, or run a Guard readiness check.

$ npm exec -y premanmcp@latest -- onboard

Run preman_status, then discover the API surface in this repository and show me which endpoints are ready to test.

The installer stores your credentials outside the project configuration. For CI or a non-interactive environment, create a pm_live_… key in PreMan settings.

Workspace

The shared place for requests, secrets, conversations, integrations, and team settings.

Project

The access boundary for Pulse runs and production logs. Link a workspace to a project explicitly.

Endpoint

A normalized method, route, schema, upstream, and source record discovered from code or imported definitions.

Guard simulation

An exact-commit contract comparison plus the runtime evidence available for that candidate.

Action contract

A versionable definition of the state that must exist after an agent claims an action succeeded.

Verification run

A verdict, check results, and bounded evidence for one reported agent action.

Store credentials as workspace secrets and reference them with tokens such as {{API_TOKEN}}. Values are substituted at execution time instead of being copied into the shared request definition.

• Generate persisted happy-path, missing-field, invalid-value, boundary, pagination, and injection cases.
• Choose read_only, allow_writes, or allow_destructive as the standing authorization.
• Schedule endpoint probes from 30 to 3,600 seconds and inspect result history.
• Trigger rules for consecutive failures, error rate, or p95 latency.
• Send alerts through email or Slack, including bounded evidence and recovery notices.

$ npx preman-sdk monitor --endpoint-id <id> --interval-seconds 60 --expected-status 200

1. 01
   Signed push

   GitHub sends an authenticated delivery for the selected repository and immutable repository id.

2. 02
   Exact source scan

   PreMan checks out the full SHA and produces a bounded field-level contract diff.

3. 03
   Runtime scenarios

   Read-only probes or approved suites exercise the candidate environment.

4. 04
   Build attestation

   Every runtime response must identify the exact commit before it becomes trusted evidence.

5. 05
   Verdict

   Guard separates impact, green evidence, missing coverage, and repositories with no API surface.

The first successful default-branch simulation establishes the baseline. Later default-branch pushes advance it only when GitHub still reports that commit as the branch head. Other branches are previews and do not replace the published baseline.

Candidate responses can attest the commit through headers including X-PreMan-Build-Commit, X-Git-Commit, or X-Commit-Sha, or through standard JSON health fields such as commit_sha. Full 40-character SHAs are required.

When responses attest a different build, Impact Simulation reports the active commit serving that traffic alongside the selected candidate. If traffic spans a rolling or split deployment, it reports each observed commit and its response count instead of choosing one arbitrarily.

1. Link the workspace to a project. Workspace membership and project membership are separate; production log access follows the project.
2. Connect AWS. Deploy the generated read-only cross-account role, select a CloudWatch log group, and test reachability.
3. Inspect the live signal. Use Graph, List, and History without losing the selected route.
4. Reproduce or investigate. Open the saved request, correlated logs, or an agent task from the same endpoint context.

Use Verified Actions when a valid tool response is not enough—for example, when a refund can have the wrong amount, an appointment can be missing from the scheduler, or a CRM update can land on the wrong record.

{
  "action_type": "issue_refund",
  "contract_key": "shopify_refund_v1",
  "source": "customer-agent",
  "external_action_id": "refund_1049",
  "customer_ref": "store_842",
  "request_payload": {
    "order_id": "1049",
    "amount": 82
  },
  "claimed_result": {
    "order_id": "1049",
    "refund": { "amount": 82 },
    "status": "refunded"
  },
  "idempotency_key": "refund_1049"
}

The create call returns both the action event and its verification run. A run may remain pending while the consistency window is open. Read it with GET /verification/runs/{run_id}, or use POST /verification/runs/{run_id}/grade when an operator needs an immediate terminal attempt.

Shopify and HubSpot reads use bounded timeouts and response limits. Authentication failure, missing objects, unreachable systems, and upstream errors remain distinct evidence states.

{
  "mcpServers": {
    "payments-api": {
      "url": "https://api.preman.live/h/<hosted-mcp-id>/mcp",
      "headers": {
        "Authorization": "Bearer pm_hmcp_<consumer-token>"
      }
    }
  }
}

Hosted runtimes support initialize, tools/list, tools/call, ping, and JSON-RPC batches. Public mode needs only the URL; token mode requires a scoped consumer token.

Remote Streamable HTTP MCP import is currently Beta: PreMan can wrap a compatible remote server in the hosted gateway. The broader experience for importing multiple stdio, SSE, and HTTP servers into one governed profile is still Preview and has no stable public API.

$ npm exec -y premanmcp@latest -- onboard

$ npm install preman-sdk

$ preman verify --pre-push

Pre-push checks scan changed API sources, include shared-model neighbors, and can rank tests with observed route volume. Blocking is opt-in; crashes and timeouts do not block a push by default.

• Manual destructive requests require one-run approval.
• Scheduled execution defaults to read-only authorization.
• Runtime attestation fails closed on missing, short, or mismatched commit ids.
• Repair automation opens review work; it does not merge or deploy.