Quickstart

Route your first proposed AI action through Sector8 and honor the returned decision.

Quickstart

For the full unassisted journey (install → ALLOW/DENY → evidence → observe/enforce), start at Onboarding. This page is a short reference.

This guide gets you to the first important proof point: your application asks Sector8 whether a proposed AI action may execute, then your runtime honors the returned decision.

Use the endpoint and credentials issued for your environment.

Prerequisites

• A Sector8 x-api-key
• A Sector8 x-client-id
• The base URL for your environment
• A runtime path where you can block execution when Sector8 returns DENY

export SECTOR8_BASE_URL="https://sdkapi.sector8.ai"
export SECTOR8_API_KEY="YOUR_API_KEY"
export SECTOR8_CLIENT_ID="YOUR_CLIENT_ID"

Replace SECTOR8_BASE_URL with the endpoint issued to your environment when it differs from the public production example.

---

Step 1: Check the gate

Confirm the endpoint is healthy before routing actions through it.

curl -s "$SECTOR8_BASE_URL/api/health"

Expect a healthy response with active invariants and gate capabilities. If this check fails, do not route live actions until the endpoint is reachable.

---

Step 2: Prove DENY and ALLOW

Send the action you are about to execute to Sector8 first. Use one known-blocked action and one safe action so your runtime proves both sides of the contract.

DENY proof

curl -s "$SECTOR8_BASE_URL/api/v1/evaluate" \
  -H "x-api-key: $SECTOR8_API_KEY" \
  -H "x-client-id: $SECTOR8_CLIENT_ID" \
  -H "content-type: application/json" \
  -d '{
    "tool_name": "bash",
    "arguments": {
      "command": "cat .env"
    },
    "caller_id": "quickstart-agent",
    "role": "developer",
    "session_id": "quickstart-session-deny",
    "operation": "read"
  }'

You should receive a decision artifact like:

{
  "decision": "DENY",
  "reason_code": "SENSITIVE_PATH_BLOCKED",
  "evidence_hash": "bdbde1558fb883573b0f6e8630ccba1edaf6bed8cb035fa6a48912809149f287",
  "has_forensic_payload": true,
  "decision_trace_id": "32819155-d21a-49c8-9509-79338d980fa9",
  "policy_version_id": "5d61927dcac73a97e9e3c7ee0dbca364d66447469637bafa2282e635124fcb99"
}

Your runtime must not dispatch this action.

Branch on decision, not on a specific reason_code. The same unsafe command may return different reason codes depending on which policy layer blocks it.

ALLOW proof

curl -s "$SECTOR8_BASE_URL/api/v1/evaluate" \
  -H "x-api-key: $SECTOR8_API_KEY" \
  -H "x-client-id: $SECTOR8_CLIENT_ID" \
  -H "content-type: application/json" \
  -d '{
    "tool_name": "bash",
    "arguments": {
      "command": "echo hello"
    },
    "caller_id": "quickstart-agent",
    "role": "developer",
    "session_id": "quickstart-session-allow",
    "operation": "read"
  }'

You should receive a decision artifact like:

{
  "decision": "ALLOW",
  "reason_code": "ALLOW_PASS",
  "evidence_hash": "4cb7f786d1f3b57e6f98f3e60d2eb6b81c402d6d3efeb6c9551049f7c14df2f0",
  "has_forensic_payload": false,
  "decision_trace_id": "17e797c0-eb5c-4f97-b4a1-2d3e4f5a6b7c",
  "policy_version_id": "0dbca364d66447469637bafa2282e635124fcb99eecd6383038e3b652577ebc7"
}

Your runtime may dispatch only after this ALLOW.

reason_code and policy_version_id are opaque support/evidence identifiers. Do not build exhaustive dispatch logic on them. Treat policy_version_id as a non-empty policy identifier — it may be a binding hash or a runtime version label depending on the evaluation path. REST responses use the field decision. Some SDKs expose the same value as outcome — check for ALLOW the same way either way.

---

Step 3: Honor the decision

Your application must only dispatch the proposed action when Sector8 allows it.

import os
import httpx

try:
    response = httpx.post(
        f"{os.environ['SECTOR8_BASE_URL']}/api/v1/evaluate",
        headers={
            "x-api-key": os.environ["SECTOR8_API_KEY"],
            "x-client-id": os.environ["SECTOR8_CLIENT_ID"],
        },
        json={
            "tool_name": "bash",
            "arguments": {"command": "cat .env"},
            "caller_id": "quickstart-agent",
            "role": "developer",
            "session_id": "quickstart-session",
            "operation": "read",
        },
        timeout=10.0,  # recommended default; fail-closed on timeout
    )
    response.raise_for_status()
    decision = response.json()
except Exception as exc:
    print(f"Gate unavailable or invalid response; failing closed: {exc}")
    raise SystemExit(1)

# REST uses `decision`. Some SDKs expose the same value as `outcome`.
decision_value = decision.get("decision") or decision.get("outcome")

if decision_value == "ALLOW":
    # Dispatch the tool call here.
    pass
elif decision_value == "DENY":
    print(f"Blocked before execution: {decision.get('reason_code')}")
    print(f"Evidence hash: {decision.get('evidence_hash')}")
else:
    print(f"Unknown decision contract; failing closed: {decision}")
    raise SystemExit(1)

Fail closed if the evaluate call fails, times out, or returns an unknown decision. Do not execute the proposed action by default.

Set an evaluate client timeout of at least 10 seconds (10s is a safe default for most apps). Observed evaluate latency is commonly about 1–4 seconds on the public production host, but slower environments and cold paths can take longer. An aggressive 1–2s timeout will fail closed on legitimate ALLOW traffic and block your own safe actions.

REST field: decision. SDK field: often outcome. Both carry ALLOW or DENY for synchronous evaluate. Dispatch only on ALLOW.

---

Choose your integration path

MCP runtime

Govern Claude Code and MCP-connected tool calls with a runtime connector.

Python SDK

Add Sector8 to Python applications and services.

TypeScript SDK

Add Sector8 to Node.js and TypeScript applications.

If your runtime dispatches tools directly, use the REST evaluate API or the non-MCP integration guide.

---

What success looks like

You are done when:

• The health endpoint is reachable for your environment
• Your runtime calls /api/v1/evaluate before dispatching the action
• ALLOW actions may execute
• DENY actions are blocked before execution
• Unknown or missing decisions fail closed and do not execute
• Decision artifacts include reason_code, decision_trace_id, evidence_hash, and policy_version_id

The key integration rule is simple: the agent proposes, Sector8 decides, and your runtime honors the decision before side effects start.