How to Run AI Agents Safely from the Terminal

SafeClaw by Authensor provides a CLI-first approach to AI agent safety, enforcing deny-by-default action gating directly from your terminal. Whether you run AI agents through shell scripts, CI pipelines, or interactive sessions, SafeClaw intercepts every action and checks it against your policy before it executes. It supports Claude and OpenAI agents and is backed by 446 tests with hash-chained audit logging.

Prerequisites

• A Unix-like terminal (bash, zsh, fish) or Windows Terminal
• Node.js 18+
• An AI agent tool or SDK

Step 1: Install SafeClaw

Run the following command in your terminal:

npx @authensor/safeclaw

This initializes SafeClaw in your current directory, creating the .safeclaw/ folder with a default deny-all policy and an empty audit log.

Step 2: Create a Policy File

Write your policy rules in .safeclaw/policy.yaml:

version: 1
default: deny

rules:
  - action: file.read
    paths:
      - "**"
    decision: allow

- action: file.write
    paths:
      - "output/**"
      - "tmp/**"
    decision: allow

- action: shell.execute
    commands:
      - "git status"
      - "git diff"
      - "npm test"
    decision: allow

- action: shell.execute
    decision: deny

- action: network.request
    domains:
      - "api.openai.com"
      - "api.anthropic.com"
    decision: allow

This policy allows file reads everywhere, restricts writes to output/ and tmp/, permits only specific shell commands, and blocks all other shell execution.

Step 3: Wrap Your Agent with SafeClaw

Instead of running your AI agent directly, wrap it with SafeClaw:

npx @authensor/safeclaw wrap -- node my-agent.js

The wrap command starts SafeClaw as a middleware layer around your agent process. Every action the agent attempts flows through SafeClaw's policy engine before reaching the operating system.

Step 4: Run in Interactive Mode

For real-time control, use interactive mode:

npx @authensor/safeclaw interactive

In interactive mode, actions with a prompt decision pause and display a confirmation dialog in your terminal:

[SafeClaw] Action: file.write
  Target: src/main.js
  Policy: prompt
  Allow this action? [y/N]:

Type y to allow or n (or just press Enter) to deny. Every decision is recorded in the audit log.

Step 5: Review the Audit Log

After running your agent, inspect the audit trail:

npx @authensor/safeclaw audit --tail 20

Each entry includes a timestamp, action type, target resource, policy decision, and a SHA-256 hash linking to the previous entry. Verify the entire chain has not been tampered with:

npx @authensor/safeclaw audit --verify

If any entry has been modified, the hash chain breaks and SafeClaw reports the exact point of corruption.

Step 6: Add Shell Aliases for Convenience

Add these to your .bashrc or .zshrc:

alias sc="npx @authensor/safeclaw"
alias sc-audit="npx @authensor/safeclaw audit --tail 20"
alias sc-verify="npx @authensor/safeclaw audit --verify"
alias sc-status="npx @authensor/safeclaw status"

Now you can type sc-audit to see recent entries or sc-verify to check chain integrity.

Step 7: Use in Scripts and CI

SafeClaw supports non-interactive mode for automation:

npx @authensor/safeclaw wrap --non-interactive --strict -- node my-agent.js

The --strict flag treats any prompt decisions as deny, ensuring fully automated pipelines never hang waiting for input. This is ideal for CI/CD environments.

Summary

SafeClaw provides comprehensive terminal-based AI agent safety with deny-by-default policies, interactive confirmation prompts, and tamper-evident audit logs. The CLI-first design means it works everywhere a terminal does, from local development to remote servers to CI runners. SafeClaw is MIT licensed and open source.

Related Guides

• How to Add AI Agent Safety to VS Code
• How to Secure AI Agents in GitHub Codespaces
• How to Send AI Agent Safety Alerts to Slack
• How to Set Up Custom Webhooks for AI Agent Events
• How to Send AI Agent Audit Logs to Splunk