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.
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 reviewed 0.8.0.dev0 source candidate 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 reviewed 2.0.0-dev.0 source candidate 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

All SDKs read credentials from environment variables and should run in a backend service, worker, or trusted server-side tool wrapper. Published Python, TypeScript, and Go baselines remain separate from the replay-safe repository source candidates. Java 17 source builds and focused replay tests pass locally, but registry publication is not externally verified. Rust is first-party preview source with no verified remote package, and executable verification remains pending because a Rust toolchain was unavailable on this host.

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 Standard-contract refund.create guard

This example uses the released Python package and the live Standard contract. Use the replay-safe source candidate 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.

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.