Getting Started with SafeClaw: From Zero to Safe in 5 Minutes

Authensor Team · 2026-02-13

Getting Started with SafeClaw: From Zero to Safe in 5 Minutes

This is our walkthrough for going from zero to a fully gated AI agent. By the end, you will have SafeClaw installed, a provider configured, a safety policy active, and an agent running with every action checked before it executes.

Prerequisites

You need Node.js v20 or later. Check with:

``bash


node --version



If you do not have it, download it from nodejs.org. That is the only prerequisite.

You also need an API key from either Anthropic (for Claude) or OpenAI (for GPT-4o). If you do not have one yet, you can get them from console.anthropic.com or platform.openai.com.

Step 1: Install and Launch

bash
npx @authensor/safeclaw



This downloads SafeClaw, starts the localhost server on port 7700, and opens the browser dashboard. No global install required. No configuration files to create manually.

If you prefer to clone the repository:

bash
git clone https://github.com/AUTHENSOR/SafeClaw.git && cd SafeClaw
npm install && npm start



Step 2: The Setup Wizard

The dashboard opens to the Setup Wizard tab. Here is what to configure:

Provider. Choose Claude (default) or OpenAI. Claude uses the Anthropic Agent SDK. OpenAI uses our custom agent loop with GPT-4o.

API Key. Paste your Anthropic or OpenAI API key. The key is stored locally in

~/.safeclaw/.env with mode 0o600

 (owner-read-write only). It is never sent to Authensor or any external service.

Authensor Token. The wizard can auto-provision a demo token for you. Click "Get Demo Token" and it is done. For production use, you will configure a proper Authensor account later.

Click "Save & Continue." SafeClaw runs a post-init health check (the doctor command) and shows you the results. Green checks mean everything is configured correctly.



Step 3: Understand the Default Policy

SafeClaw ships with a default policy that is safe out of the box. Here is what it does:

| Action | Policy Decision | What It Means |
|--------|----------------|---------------|
| Read files, search, grep | Allow | Safe read operations pass through instantly with no network call |
| Write/edit files | Require approval | You review and approve before the file is modified |
| Shell commands | Require approval | You see the exact command before it runs |
| Network requests | Require approval | HTTP requests and web searches need your okay |
| MCP tool calls | Require approval | Third-party tool interactions are gated |
| Everything else | Deny | Unknown actions are blocked entirely |

You do not need to modify this policy to get started. It is designed to be usable immediately while keeping you in control of every potentially dangerous action.

Step 4: Run Your First Task

Switch to the Task Runner tab in the dashboard. Type a task like:

> "Read the files in this directory and summarize what you find"

Click "Run Task." The agent starts working. You will see its conversation in real-time as chat bubbles with live streaming.

Since reading files is a safe-read operation, the agent proceeds without interruption. Now try something more interesting:

> "Create a file called hello.txt with the contents 'Hello from SafeClaw'"

This time, the agent wants to write a file. SafeClaw intercepts the action, classifies it as filesystem.write, and holds it for your approval. You will see an approval card appear in the stream:

Action type: filesystem.write

Resource: /path/to/hello.txt


Buttons: Approve / Reject


Click "Approve" and the file is created. Click "Reject" and the agent is told the action was denied. Either way, the decision is logged to the audit ledger.

Step 5: Explore the Dashboard

Now that you have the basics, explore the other tabs:

Approvals tab. Lists all pending approval requests. If you have the dashboard open on your phone (navigate to

http://localhost:7700

), you can swipe right to approve and left to reject.

Analytics tab. Shows cost tracking, approval metrics, and tool usage breakdown. After running a few tasks, this tab gives you a clear picture of what your agent does and how much it costs.

Policy Editor tab. Visual interface for viewing and editing your policy rules. You can add new rules, modify existing ones, test rules with the simulation panel, and rollback to previous policy versions.

Settings tab. Configure timeouts, budget controls, webhook notifications (Slack, Discord), and SMS alerts (Twilio).

Claw Clinic tab. Diagnostic checks for your SafeClaw setup. Run these if something seems wrong -- it checks control plane connectivity, API key validity, policy integrity, audit chain verification, and more.

Step 6: Run from the CLI

Everything you can do in the dashboard, you can also do from the terminal:

bash
Run a task
safeclaw run "write a unit test for the login function"

Run in container mode (requires Docker or Podman)
safeclaw run --container "analyze the codebase for security issues"

Dry-run: preview what would happen without starting the agent
safeclaw run --dry-run "deploy the application"

View pending approvals
safeclaw approvals

View the audit trail
safeclaw audit

Verify audit chain integrity
safeclaw audit verify

Check system health
safeclaw doctor



Step 7: Customize Your Policy

As you use SafeClaw, you will learn which actions your agent takes regularly. Add policy rules to reduce approval fatigue for safe, repetitive actions:

From the Policy Editor in the dashboard, click "Add Rule" and create a rule like:

Effect: allow

Condition: action.type equals code.exec AND action.resource starts with npm test


Description: "Allow running npm test without approval"

Save the policy. Now npm test` commands execute immediately while everything else still requires your approval.

For detailed policy syntax and more examples, see our policy rule documentation.

What Happens Behind the Scenes

Every action your agent takes follows this path:

The agent decides to call a tool

SafeClaw's gateway intercepts the call before execution

The classifier maps the tool to an action type and extracts the resource

The policy engine evaluates the action against your rules

The decision is enforced: allow, deny, or hold for approval

The decision is logged to the tamper-proof audit ledger

The action executes (or does not)

This happens for every tool call, every time. No exceptions.

Next Steps

Read the architecture deep-dive to understand how gating works under the hood
Explore container mode for additional environment isolation
Check the SafeClaw documentation for the complete quickstart reference
Browse the source code -- it is all open

Welcome to safe-by-default AI agents.