Protect your first action.

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.
Use a stable idempotency key such as refund:{refund_id} or action:{resource_id}.
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.
Use a stable idempotency key such as refund:{refundId} or action:{resourceId}.
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

All SDKs read credentials from environment variables and should run in a backend service, worker, or trusted server-side tool wrapper. Python, TypeScript, and Go external installs are verified. Java preview metadata is verified on JitPack, while Maven Central is not published. Rust is first-party preview source with no verified remote package yet.

Environment variables

HALTSTATE_TENANT_ID and HALTSTATE_API_KEY are workspace credentials. If you already have access, sign in from the Login link. If you need a private workspace, fleet rollout, SSO, retention, regulated workflow, licensing, partnership, or architecture discussion, use the Enterprise path. Hands-on SDK installation should be handled with the coding-agent prompt or your internal engineering workflow.

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

Minimal refund.create guard

from haltstate import HaltStateClient, ApprovalPending, ActionDenied

client = HaltStateClient(
    tenant_id=os.environ["HALTSTATE_TENANT_ID"],
    api_key=os.environ["HALTSTATE_API_KEY"],
)

try:
    with client.guard(
        action="refund.create",
        params={"amount": 126, "currency": "USD"},
        idempotency_key="refund:order-1001",
    ):
        simulated_ledger.write_refund()
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.

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.