Developer integrations

Everything an application or pipeline needs to route traffic through governance: the zero-dependency CLI, the language-neutral HTTP contract, the Python auto-hook, CI recipes that prove policy is enforced, and local verification of signed workflow bundles.

Workload credentials

Every path below authenticates as a registered workload. Register one in the dashboard (Agents → Register), then export:

export KAVROS_API_URL="https://<data-plane-host>/api/agent/egress"
export KAVROS_API_KEY="<workload-api-key>"
export KAVROS_AGENT_ID="<workload-id>"

CLI: @kavrosai/cli

Zero runtime dependencies, Node 18+. The fastest way from an empty shell to proof that governance works.

npx @kavrosai/cli doctor          # connectivity + identity check

kavros request --action get \
  --target "https://docs.example.com" --json

kavros help request                # per-command options

Understand any failure

Blocked requests print what happened, whether content left your network (blocked requests never do), and what to do next — the same explanation is available standalone:

kavros explain 403 --body \
  '{"error":"Blocked by Kavros",
    "reason":"target not in allowlist"}'

Verify a signed bundle locally

Before importing a workflow bundle from another deployment, verify its Ed25519 signature offline — the same check the import route performs:

kavros verify-bundle workflow.kavros-bundle.json \
  --public-key "$CP_POLICY_PUBLIC_KEY"

Bundle verification reports the workflow, revision, origin deployment, pinned capabilities, and the verifying key's fingerprint — paste it into your change record as promotion evidence.

Native HTTP from any language

The CLI is a convenience — the product contract is this JSON request. Go, Rust, Java, Ruby, Python, or anything that speaks HTTP:

curl --fail-with-body --silent --show-error \
  --request POST "$KAVROS_API_URL" \
  --header "Authorization: Bearer $KAVROS_API_KEY" \
  --header "X-Kavros-Agent-ID: $KAVROS_AGENT_ID" \
  --header "Content-Type: application/json" \
  --data '{
    "action": "post_data",
    "target": "https://api.example.com/v1/run",
    "content": "{\"input\":\"hello\"}",
    "headers": {"content-type": "application/json"}
  }'

Blocks return HTTP 403 with {"error":"Blocked by Kavros","reason":"…","logs":[…]}. Read reason, not the first log line. See Agent Integration for the full contract.

Python zero-code hook

kavros-agent patches requests and httpx at interpreter startup — Anthropic/OpenAI SDK calls are routed through governance with no code changes:

python -m pip install kavros-agent
export KAVROS_API_URL=… KAVROS_API_KEY=… KAVROS_AGENT_ID=…
python app.py   # traffic now flows through the data plane

The hook is a no-op when Kavros variables are absent, so installing the wheel never affects unconfigured processes.

CI recipe: prove governance in every pipeline run

A governed deployment is testable: an allowed request must succeed, and a forbidden request must be blocked. Asserting both turns policy drift into a failing build instead of a surprise. The blocked-target check is the important one — it proves the data plane is actually in the path, not just reachable.

# .github/workflows/governance.yml
name: governance-smoke
on: [push, schedule]

jobs:
  governed-egress:
    runs-on: ubuntu-latest   # must reach the data plane (self-hosted runner in VPC deployments)
    steps:
      - name: Install CLI
        run: npm install --global @kavrosai/cli

      - name: Connectivity and identity
        run: kavros doctor
        env:
          KAVROS_API_URL:  ${{ secrets.KAVROS_API_URL }}
          KAVROS_API_KEY:  ${{ secrets.KAVROS_API_KEY }}
          KAVROS_AGENT_ID: ${{ secrets.KAVROS_AGENT_ID }}

      - name: Allowed request succeeds
        run: kavros request --action get --target "$APPROVED_TARGET" --json >/dev/null

      - name: Forbidden request is blocked (policy is in the path)
        run: |
          if kavros request --action get --target "$FORBIDDEN_TARGET" >/dev/null 2>&1; then
            echo "::error::Policy did not block a forbidden target — check the data plane path."
            exit 1
          else
            echo "Policy enforced: forbidden target was blocked."
          fi
        env:
          FORBIDDEN_TARGET: "https://nonapproved.example.internal"

GitLab CI: the same three steps in .gitlab-ci.yml under a governance stage. For pipeline-level bundle promotion, run kavros verify-bundle before any import step and fail the job on a non-zero exit.

Cross-deployment promotion, verified

Moving a workflow from staging to production crosses a trust boundary. Export produces a signed, immutable bundle; import refuses anything the local policy key did not sign. Verify in between — by hand or in CI:

# on staging (dashboard): Workflows → Export bundle
# in production's pipeline, before import:
kavros verify-bundle nightly-report.kavros-bundle.json \
  --public-key "$CP_POLICY_PUBLIC_KEY" --json
# → "Signature valid" names workflow, revision, capabilities, key fingerprint
# only then: dashboard → Workflows → Import bundle

Troubleshooting quick reference

HTTP 403 · "Blocked by Kavros"

A governed denial, not a malfunction. The named rule decided the outcome; content never left. Ask your admin to change policy if the target is legitimate.

HTTP 401/403 without the block body

Identity rejected before policy evaluation: key/ID mismatch, rotated key, or halted workload (see the Agent Registry).

HTTP 429

Quota exhausted. The request was refused at the data plane; an admin can see which workload is consuming budget in Usage.

HTTP 502/504

Policy checks passed; the approved target itself failed after egress. Target-side, not policy-side.

Connection refused / timeout

The workload network cannot reach the data plane, or KAVROS_API_URL points at the control plane UI instead of /api/agent/egress.

Run kavros explain <status> for this guidance from your terminal.