How to Add AI Agent Safety to CircleCI

SafeClaw by Authensor integrates into CircleCI pipelines to validate AI agent safety policies, run simulation tests, and verify audit trail integrity before deployment. By adding SafeClaw jobs to your CircleCI configuration, you ensure every build is checked against your deny-by-default policy before it ships. Install with npx @authensor/safeclaw and gate your AI agent deployments through CircleCI.

Prerequisites

• A CircleCI project connected to your repository
• Node.js 18+ (use a CircleCI Docker image)
• SafeClaw initialized in your project

Step 1 — Basic Safety Job

Create or update .circleci/config.yml:

version: 2.1

executors:
  node:
    docker:
      - image: cimg/node:20.0

jobs:
  safety-validate:
    executor: node
    steps:
      - checkout
      - restore_cache:
          keys:
            - deps-{{ checksum "package-lock.json" }}
      - run: npm ci
      - save_cache:
          key: deps-{{ checksum "package-lock.json" }}
          paths:
            - node_modules
      - run:
          name: Validate SafeClaw Policy
          command: npx @authensor/safeclaw validate
      - run:
          name: Run Simulation Tests
          command: npx @authensor/safeclaw test --simulation --output /tmp/safeclaw-report.json
      - store_artifacts:
          path: /tmp/safeclaw-report.json

test:
    executor: node
    steps:
      - checkout
      - restore_cache:
          keys:
            - deps-{{ checksum "package-lock.json" }}
      - run: npm ci
      - run: npm test

deploy:
    executor: node
    steps:
      - checkout
      - restore_cache:
          keys:
            - deps-{{ checksum "package-lock.json" }}
      - run: npm ci
      - run: npx @authensor/safeclaw
      - run: npm run deploy

workflows:
  build-and-deploy:
    jobs:
      - safety-validate
      - test
      - deploy:
          requires:
            - safety-validate
            - test
          filters:
            branches:
              only: main

The safety-validate and test jobs run in parallel. The deploy job requires both to pass.

Step 2 — Reusable Orb Command

Create a reusable command for use across multiple projects:

version: 2.1

commands:
  safeclaw-check:
    description: "Run SafeClaw policy validation and simulation"
    parameters:
      policy:
        type: string
        default: "safeclaw.config.yaml"
    steps:
      - run:
          name: Validate SafeClaw Policy
          command: npx @authensor/safeclaw validate --config << parameters.policy >>
      - run:
          name: Run Simulation Tests
          command: npx @authensor/safeclaw test --simulation --config << parameters.policy >>

jobs:
  safety:
    executor: node
    steps:
      - checkout
      - run: npm ci
      - safeclaw-check:
          policy: safeclaw.config.yaml

Step 3 — Policy Change Detection

Use CircleCI's path filtering to trigger additional checks when the policy file changes:

workflows:
  build-and-deploy:
    jobs:
      - safety-validate
      - policy-diff:
          filters:
            branches:
              ignore: main
      - deploy:
          requires:
            - safety-validate

policy-diff:
    jobs:
      - policy-review:
          steps:
            - checkout
            - run: npm ci
            - run:
                name: Show policy diff
                command: npx @authensor/safeclaw diff --base origin/main --head HEAD

Step 4 — Environment-Specific Policies

Test different policies for staging and production:

jobs:
  safety-staging:
    executor: node
    steps:
      - checkout
      - run: npm ci
      - run: npx @authensor/safeclaw validate --config policies/staging.yaml
      - run: npx @authensor/safeclaw test --simulation --config policies/staging.yaml

safety-production:
    executor: node
    steps:
      - checkout
      - run: npm ci
      - run: npx @authensor/safeclaw validate --config policies/production.yaml
      - run: npx @authensor/safeclaw test --simulation --config policies/production.yaml

workflows:
  build:
    jobs:
      - safety-staging:
          filters:
            branches:
              only: develop
      - safety-production:
          filters:
            branches:
              only: main

Step 5 — Post-Deploy Audit Verification

After deployment, verify the audit trail:

jobs:
  audit-verify:
    executor: node
    steps:
      - checkout
      - run: npm ci
      - run:
          name: Verify audit chain integrity
          command: npx @authensor/safeclaw audit verify --last 100

workflows:
  build-and-deploy:
    jobs:
      - safety-validate
      - deploy:
          requires:
            - safety-validate
      - audit-verify:
          requires:
            - deploy

Step 6 — Store Secrets in CircleCI Context

Use CircleCI Contexts to manage environment-specific secrets:

workflows:
  build-and-deploy:
    jobs:
      - deploy:
          context: production-secrets

SafeClaw never requires LLM API keys during CI. Policy validation and simulation run without making real API calls. Only the deploy step needs production credentials.

SafeClaw's 446-test suite ensures the policy engine behaves identically in CI and production. What passes simulation in CircleCI will enforce correctly at runtime.

Related Pages

• CI/CD Pipeline Agent Safety
• Pre-Deploy AI Safety Checks
• Simulation Mode Explained
• Policy-as-Code Pattern