Configuration

This page is the long-form walkthrough of how to configure the SDK and the dashboard for your workload. For quick lookup of types and defaults, see SDK API reference.

Where configuration lives

Arclasp configuration lives in two places:

arclasp.init() in your application — backend connection, timeouts, retries, sanitization, and approval fallback/timeout settings. Pass values as keyword arguments.
Dashboard at app.proofrail.dev — the org’s enforced policy thresholds, approvers, agent registry, kill switch, budget configuration.

The SDK does not currently read configuration from environment variables — every value must be passed to init(). If you want to keep secrets like api_key out of your code, read them from your own env var or secrets manager and pass the value to init() yourself.

Minimal configuration

The smallest viable init against hosted Arclasp:

import arclasp

arclasp.init(api_key="prail_...", backend_url="https://api.proofrail.dev")

backend_url defaults to http://localhost:8000, so pass it explicitly for hosted use. For a real workload you’ll probably want at least:

import os
import arclasp

arclasp.init(
    api_key=os.environ["ARCLASP_API_KEY"],   # read it yourself
    backend_url="https://api.proofrail.dev",
    environment="production",
    fallback_approvers=["lead@company.com"],
)

The ARCLASP_API_KEY env var here is a convention you control — the SDK doesn’t look for it automatically.

Environment tagging

environment="production" (or "staging", "development") tags every chain with that environment. The dashboard filters chains by environment, so you can keep production and staging audit trails separate without separate accounts. The default is "production". Don’t leave this as the default if you’re also running locally — your test runs will show up alongside real production activity. A common pattern:

import os
import arclasp

arclasp.init(
    api_key=os.environ["ARCLASP_API_KEY"],
    environment=os.environ.get("APP_ENV", "development"),
)

Financial thresholds

Two thresholds, both in USD:

# Per-chain cumulative override — actually reaches the backend.
# Must be set before the chain starts (before entering `async with`).
chain = arclasp.Chain("high-value-workflow")
chain.add_financial_threshold(usd=2000.0)

async with chain:
    ...

Single-transaction threshold — any one action with a top-level amount, amount_usd, or value key exceeding this requires approval. Enforced server-side; the default is **

5,000** for a fresh organization with no custom policy. This is what the [quickstart](/quickstart)'s

6,000 example relies on.

financial_approval_threshold_usd passed to arclasp.init() does not currently change the backend-enforced threshold — it only fed the deprecated local fast-path, which governed execution no longer uses. The threshold that’s actually enforced comes from your organization’s policy configuration on the backend (default $5,000). There is currently no customer-facing dashboard control to change it from the default.

Cumulative chain threshold — sum of financial values across the chain. Backend default: $10,000. Per-chain, you can override it before the chain starts with chain.add_financial_threshold(usd=...) (or Chain(policy_config={...})) — this value is sent to the backend as part of chain creation. See SDK API for add_financial_threshold(). A hard-deny threshold ($50,000 cumulative) sits above these — it applies to cumulative chain financial exposure, not a single transaction. Above that, the action is denied outright with no approval option. This threshold is currently a fixed value in the policy engine, not configurable via init(), per-chain policy_config, or the dashboard.

External domain allowlist

arclasp.init(
    api_key="...",
    external_domains_allowlist=["clients.com", "vendor.com", "*.example.com"],
)

Domains in this list are considered “internal” for the purposes of exfiltration checks. Sending data to allowlisted domains doesn’t trigger approval; sending to non-allowlisted domains does — governed by the org’s backend policy configuration. Wildcard subdomains are supported (*.example.com matches api.example.com, mail.example.com, etc.).

Like financial_approval_threshold_usd, this list is not currently sent to the backend when passed to arclasp.init() — it only fed the deprecated local fast-path. The enforced allowlist lives in your organization’s backend policy configuration.

High-risk agents

arclasp.init(
    api_key="...",
    high_risk_agents=["payment-agent", "deploy-agent", "data-export-agent"],
)

Every action by these agents requires approval, regardless of what the action is. Use this for agents that have access to high-stakes tools and shouldn’t run unsupervised. The dashboard’s agent registry independently supports marking an agent’s risk_tier as high, which the backend does enforce. The SDK-side high_risk_agents list on init() is not currently sent to the backend and, like the thresholds above, only fed the deprecated local fast-path — use the dashboard agent registry for enforced high-risk-agent behavior.

Approval timeout and fallback

arclasp.init(
    api_key="...",
    default_approval_timeout_hours=24,
    fallback_approvers=["lead@company.com", "cto@company.com"],
)

Timeout — approvals expire and auto-deny after this many hours. Default 24. Use a short timeout (0.25 for 15 minutes) for chatbots and customer-facing workflows; a long timeout (168 for 7 days) for batch jobs that can wait. Fallback approvers — if no primary approver responds in half the timeout window, the approval escalates to this list. Default empty (no fallback). If you only need fallback (no specific primary list), the SDK uses your organization’s full approver list as primary and the configured list as fallback.

Failure handling: backend unavailability always fails closed

arclasp.init(
    api_key="...",
    backend_timeout_seconds=5.0,
)

When the SDK can’t reach the backend within backend_timeout_seconds (after retries), record_agent_action() raises BackendUnavailableError — the action does not execute. This is true regardless of fail_mode / fail_modes. fail_mode="allow" (or any fail_modes entry set to "allow") is accepted for call-signature compatibility but is deprecated and ineffective: the SDK emits a DeprecationWarning and still fails closed. There is no local offline buffering or “proceed and sync later” path in governed execution — every action requires an authoritative backend response. Plan for this in latency-sensitive or flaky-network deployments by raising backend_timeout_seconds and max_retries rather than relying on a fail-open mode.

Payload sanitization

Arclasp uses two separate lists for redacting sensitive data — one matches on field names, the other on value prefixes.

arclasp.init(
    api_key="...",
    sensitive_field_patterns=["internal_user_id", "customer_dob"],
    sensitive_value_patterns=["acme_token_"],
    max_payload_string_length=2000,
)

sensitive_field_patterns — field-name substrings (case-insensitive) that get redacted as "[REDACTED]". The SDK iterates over dict keys and redacts any key whose name contains one of these substrings. Default list:

["api_key", "password", "secret", "_token", "credit_card", "ssn", "private_key"]

sensitive_value_patterns — string-value prefixes that get redacted. The SDK uses str.startswith() to match string values and redact anything beginning with one of these. Default list:

["sk_", "pk_", "ghp_", "hf_", "eyJ", "AKIA", "prail_"]

These two lists cover different attack vectors. Field patterns catch obvious cases (a password field in a payload). Value patterns catch leaked credentials in places they shouldn’t be (an OpenAI key accidentally pasted into a payload value, or — critically — an Arclasp key starting with prail_ being logged back through the SDK by mistake). Custom patterns you pass via these kwargs are appended to the defaults, not replacing them. max_payload_string_length — strings longer than this are truncated before sending. Default 1000 characters. Raise it if you need richer payloads in your audit trail; lower it if your payloads are huge (transcripts, large JSON blobs) and bandwidth matters. Raw payloads are never persisted by Arclasp — only the sanitized version reaches storage. If you redact something locally, it’s gone for good from our side.

Fast-path local evaluation (deprecated, no effect)

arclasp.init(
    api_key="...",
    enable_local_fast_path=True,  # default — deprecated, no effect
)

enable_local_fast_path is deprecated. Setting it to True emits a DeprecationWarning at init() time and does nothing — governed record_agent_action() execution always requires backend authority now; there is no local decision path. Every action goes to the backend for evaluation. The parameter is retained only so existing init() calls don’t break.

Backend URL override

arclasp.init(
    api_key="...",
    backend_url="https://api.proofrail.dev",  # hosted Arclasp
)

Default: http://localhost:8000, for local development. You must pass backend_url="https://api.proofrail.dev" explicitly to reach hosted Arclasp — omitting it against a hosted example is the most common setup mistake. Override for:

Hosted Arclasp — https://api.proofrail.dev
Testing against a staging deployment, if you have one
Local development with the backend running on http://localhost:8000 (the default) or whatever port your local backend uses

Chain metadata

The metadata parameter on arclasp.Chain(...) accepts arbitrary JSON-serializable key/value pairs and stores them on the chain record. The SDK treats this as opaque — it does not interpret specific keys to override SDK config.

async with arclasp.Chain(
    "high-stakes-workflow",
    metadata={
        "team": "platform",
        "workflow_version": "2.1.0",
        "trace_id": "req_abc123",
    },
) as chain:
    ...

Metadata appears in the dashboard chain detail view and in the chain’s receipt. Useful for cross-referencing with your own systems but not for changing SDK behavior on a per-chain basis. If you need different approval timeouts or approver lists for different workflows, initialize the SDK once per workflow boundary with the appropriate config, or use chain.add_financial_threshold() for a per-chain financial-threshold override (see above).

Custom policies

Beyond the org-wide backend defaults, your organization can create a named policy record in the dashboard at /dashboard/policies, with a mode of enforce, shadow, or disabled:

enforce — decisions are authoritative. Default for new policies.
shadow — the pipeline runs but always returns allow; the decision it would have made is logged for later review.
disabled — the pipeline is skipped entirely for that policy.

The dashboard does not currently expose a customer-facing rule editor, JSON matching DSL, or arbitrary predicate builder — policy configuration today is the mode control plus the org-wide threshold defaults, not free-form rule authoring or per-chain-name matching. See Policies for what the default policy set covers without any custom policy at all. When a policy matches, the matching policy_name and decision_reason appear in the PolicyDecision returned from record_agent_action. For denials, they’re on the raised ActionDeniedError.

Common configurations

A few starting points. Note that backend unavailability always fails closed regardless of fail_mode (see above) — these examples focus on what’s actually configurable client-side today. Solo developer testing, hosted backend

import os
import arclasp

arclasp.init(
    api_key=os.environ["ARCLASP_API_KEY"],
    backend_url="https://api.proofrail.dev",
    environment="development",
)

Production service with a tight per-chain financial threshold

import os
import arclasp

arclasp.init(
    api_key=os.environ["ARCLASP_API_KEY"],
    backend_url="https://api.proofrail.dev",
    environment="production",
    default_approval_timeout_hours=4,
    fallback_approvers=["cto@company.com"],
)

chain = arclasp.Chain("checkout")
chain.add_financial_threshold(usd=500.0)  # tighter than the org default

async with chain:
    ...

High-latency network — raise timeouts and retries instead of relying on fail-open

import os
import arclasp

arclasp.init(
    api_key=os.environ["ARCLASP_API_KEY"],
    backend_url="https://api.proofrail.dev",
    environment="production",
    backend_timeout_seconds=15.0,
    max_retries=5,
)

Where to go next

SDK API reference

Type signatures and method docs.

Exceptions

How configuration choices surface as errors.

Policies

Concept page on how policies get evaluated.

Human approval

Approval timeouts and fallback in practice.

​Configuration

​Where configuration lives

​Minimal configuration

​Environment tagging

​Financial thresholds

​External domain allowlist

​High-risk agents

​Approval timeout and fallback

​Failure handling: backend unavailability always fails closed

​Payload sanitization

​Fast-path local evaluation (deprecated, no effect)

​Backend URL override

​Chain metadata

​Custom policies

​Common configurations

​Where to go next

SDK API reference

Exceptions

Policies

Human approval

Configuration

Where configuration lives

Minimal configuration

Environment tagging

Financial thresholds

External domain allowlist

High-risk agents

Approval timeout and fallback

Failure handling: backend unavailability always fails closed

Payload sanitization

Fast-path local evaluation (deprecated, no effect)

Backend URL override

Chain metadata

Custom policies

Common configurations

Where to go next