Connect an agent to automated policy enforcement.

From connection to automatic enforcement

1. Create your HaltState account and get your workspace credentials.
2. Connect a supported tool or API action using the SDK instructions below.
3. Use the AI Policy Assistant to help draft policies, then review and activate them through the existing policy flow.
4. Confirm automatic allow and automatic deny, then test a policy-required approval case.
5. Connect your MCP client to search activity, inspect recorded outcomes and verify evidence without returning to the dashboard for each investigation.

See how it works

Install with a coding agent

Use this route when you want Codex, Claude Code, or Cursor to add the first guarded action in a branch, show the diff, and stop before deployment.

You are adding HaltState to one Python backend action only.

Install the released package inside the backend service:
pip install haltstate-sdk

Use HALTSTATE_TENANT_ID and HALTSTATE_API_KEY from environment variables only.
Keep keys out of browser code, frontend bundles, logs and committed files.
Identify one backend side-effecting action, such as refund.create, payment.authorize, customer.message.send, PII export or a production write.
Wrap/check/report that one action with the current Python SDK.
Guard the selected action before the side effect executes.
The released Python package uses the live Standard contract. Use a stable logical idempotency key for HaltState and keep a separate stable destination idempotency key.
Do not construct an hsr1 replay key or claim replay-safe permits and receipts with the released package.
Only if an operator separately authorises the replay candidate, install the published 0.8.0.dev1 release and use the assigned activation epoch.
Handle ALLOW, APPROVAL_REQUIRED and DENY explicitly.
On ALLOW, execute the side effect once and report success or failure after the business action completes.
On APPROVAL_REQUIRED, do not execute; persist or return the pending state for human review.
On DENY, do not execute and record the denial safely.
Fail closed on HaltState auth or transport errors for money, PII and production writes.
Add or update tests for allowed, approval-required, denied and HaltState-unavailable paths.
Show the diff and stop for human review.
Do not deploy or change infrastructure.

You are adding HaltState to one TypeScript backend action only.

Install the released package inside the backend service:
npm install @haltstate/sdk

Use HALTSTATE_TENANT_ID and HALTSTATE_API_KEY from environment variables only.
Keep keys out of frontend/browser code, logs and committed files.
Identify one backend side-effecting action, such as refund.create, payment.authorize, customer.message.send, PII export or a production write.
Wrap/check/report that one action with the current TypeScript SDK.
If you use the helper, call withGuard(action, options, fn).
withGuard performs reporting and should not be manually duplicated.
For explicit reporting, pass the CheckResult to report with status success, failure or error.
Guard the selected action before the side effect executes.
The released TypeScript package uses the live Standard contract. Use a stable logical idempotency key for HaltState and keep a separate stable destination idempotency key.
Do not construct an hsr1 replay key or claim replay-safe permits and receipts with the released package.
Only if an operator separately authorises the replay candidate, install the published 2.0.0-dev.0 release and use the assigned activation epoch.
Handle ALLOW, APPROVAL_REQUIRED and DENY explicitly.
On ALLOW, execute the side effect once and report success or failure after the business action completes.
On APPROVAL_REQUIRED, do not execute; persist or return the pending state for human review.
On DENY, do not execute and record the denial safely.
Fail closed on HaltState auth or transport errors for money, PII and production writes.
Add or update tests for allowed, approval-required, denied and HaltState-unavailable paths.
Show the diff and stop for human review.
Do not deploy or change infrastructure.

First-action answers before you paste the prompt

Install manually

Choose Python, TypeScript/JavaScript, Go, Java or Rust. All five SDKs are published through the distribution links below. Run them in a backend service, worker or trusted server-side tool wrapper, with credentials in environment variables.

Environment variables

HALTSTATE_TENANT_ID and HALTSTATE_API_KEY are available after self-service signup. Keep them server-side. Hands-on SDK installation should be handled with the coding-agent prompt or your internal engineering workflow. The Enterprise path is optional for private deployments, fleet requirements or a commercial discussion—not a prerequisite for an account.

HALTSTATE_TENANT_ID=your-tenant-id
HALTSTATE_API_KEY=hs_your_api_key
HALTSTATE_API_BASE=https://haltstate.ai

Minimal Standard-contract refund.create guard

This example uses the released Python package and the live Standard contract. Use the replay-enabled SDK contract only under separate operator authorisation.

from haltstate import HaltStateClient, ApprovalPending, ActionDenied

client = HaltStateClient(
    tenant_id=os.environ["HALTSTATE_TENANT_ID"],
    api_key=os.environ["HALTSTATE_API_KEY"],
)
logical_key = "refund:order-1001"

try:
    with client.guard(
        action="refund.create",
        params={"amount": 126, "currency": "USD"},
        idempotency_key=logical_key,
    ):
        simulated_ledger.write_refund(idempotency_key=logical_key)
except ApprovalPending:
    queue_for_review()
except ActionDenied:
    do_not_refund()

Safe operator example

HALTSTATE_REFUND_AGENT_API_KEY=$HALTSTATE_API_KEY   python services/retail_refund_agent.py --once

What to verify first

• The guarded action returns ALLOW, APPROVAL_REQUIRED, or DENY before the business system is touched.
• The idempotency key is stable across retries and does not create duplicate execution records.
• Denied and pending actions do not execute.
• Post-action reports are written only after the side effect succeeds or fails.
• Public events show safe evidence and redaction status, not raw customer payloads or secrets.

What happens after the SDK connects

1. The agent/action is detected or registered.
2. The onboarding wizard guides scope and risk selection.
3. The AI Policy Assistant drafts policies.
4. A human reviews and publishes.
5. HaltState enforces actions and records Proof Packs.

The public triage page can prepare a starter action map and coding-agent prompt, but it never activates production policy.

Use your MCP client for everyday investigation

After your agents are connected, add https://haltstate.ai/mcp to a compatible client and authorize your account. Ask what an agent did, find a customer interaction, follow its timeline or verify a Proof Pack from the client you already use.

Compatible clients renew access automatically; you do not need to sign in to the dashboard for every investigation. Account setup, policies, approvals, containment, billing and connection permissions remain in the dashboard. MCP investigation does not replace SDK enforcement.

Recommended path

Start with one action that has clear business impact and clear authority rules. Refunds are ideal for retail teams because the thresholds are understandable: small clean refunds can pass, medium refunds can require approval, and duplicates or high-value refunds can be denied. After that first action is stable, add customer data access, outbound messages, production writes, or payment authorization.

Keep the first implementation boring. Put the guard in a backend service or worker, not in public browser code. Store credentials in environment variables or a secrets manager. Derive the idempotency key before the guard call. Fail closed for money, PII, and production writes. Report success only after the business action actually completes.