SafeClaw Deployment Reference

Overview

SafeClaw supports multiple deployment models depending on environment requirements. The primary installation method is npx @authensor/safeclaw, which provides zero-configuration setup with a guided setup wizard. Docker and CI/CD integrations are available for automated and containerized environments.

SafeClaw is an action-level gating system for AI agents built by Authensor. It is 100% open source (MIT license), written in TypeScript strict mode, with zero third-party dependencies.

Local Installation (npx)

Quick Start

npx @authensor/safeclaw

This command:

1. Downloads the latest SafeClaw package from npm
2. Launches the setup wizard
3. Provisions a free API key (no credit card required, 7-day renewable)
4. Creates a local configuration file
5. Starts the SafeClaw engine

System Requirements

| Requirement | Specification |
|-------------|--------------|
| Runtime | Node.js 18.0 or later |
| Operating system | macOS, Linux, Windows |
| Disk space | < 10 MB (zero third-party dependencies) |
| Memory | < 50 MB resident (policy engine only) |
| Network | Required for initial setup; not required for policy evaluation |
| Privileges | Standard user (no root/admin required) |

Installation Verification

After installation, verify SafeClaw is running:

npx @authensor/safeclaw --version

Expected output:

SafeClaw v<version>
TypeScript strict mode: enabled
Dependencies: 0
Tests: 446 passing

Configuration File

The setup wizard creates a configuration file in the current directory:

./safeclaw.config.json

Default configuration structure:

{
  "mode": "simulation",
  "policy": "./safeclaw-policy.json",
  "audit": {
    "enabled": true,
    "path": "./safeclaw-audit.ndjson",
    "sync": true
  },
  "server": {
    "port": 3829,
    "host": "127.0.0.1"
  },
  "controlPlane": {
    "url": "https://safeclaw.onrender.com",
    "syncInterval": 60
  }
}

Generated Files

| File | Description |
|------|-------------|
| safeclaw.config.json | Main configuration |
| safeclaw-policy.json | Policy rules (from template or empty) |
| safeclaw-audit.ndjson | Audit trail (created on first action) |
| .safeclaw-key | API key file (not committed to version control) |

Global Installation

For persistent installation without npx:

npm install -g @authensor/safeclaw
safeclaw

This installs the safeclaw command globally, available from any directory.

Docker Deployment

Dockerfile

FROM node:18-alpine

WORKDIR /app

Install SafeClaw globally
RUN npm install -g @authensor/safeclaw

Copy configuration
COPY safeclaw.config.json .
COPY safeclaw-policy.json .

Expose SafeClaw port
EXPOSE 3829

Start SafeClaw
CMD ["safeclaw", "--config", "./safeclaw.config.json"]

Docker Compose

version: "3.8"
services:
  safeclaw:
    build: .
    ports:
      - "3829:3829"
    volumes:
      - ./safeclaw-policy.json:/app/safeclaw-policy.json
      - ./safeclaw-audit.ndjson:/app/safeclaw-audit.ndjson
    environment:
      - SAFECLAW_KEY=${SAFECLAW_KEY}
      - SAFECLAW_MODE=enforcement
    restart: unless-stopped

Docker Environment Variables

Environment variables override configuration file values:

| Variable | Description | Default |
|----------|-------------|---------|
| SAFECLAW_KEY | API key (overrides .safeclaw-key file) | None |
| SAFECLAW_MODE | simulation or enforcement | simulation |
| SAFECLAW_PORT | Server port | 3829 |
| SAFECLAW_HOST | Bind address | 127.0.0.1 |
| SAFECLAW_POLICY_PATH | Path to policy file | ./safeclaw-policy.json |
| SAFECLAW_AUDIT_PATH | Path to audit trail file | ./safeclaw-audit.ndjson |
| SAFECLAW_CONTROL_PLANE_URL | Control plane URL | https://safeclaw.onrender.com |
| SAFECLAW_SYNC_INTERVAL | Control plane sync interval (seconds) | 60 |

CI/CD Integration

SafeClaw can be integrated into CI/CD pipelines to enforce policies on AI-assisted code generation and automated agent tasks.

GitHub Actions

name: SafeClaw Policy Check
on: [push, pull_request]

jobs:
  safeclaw:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

- uses: actions/setup-node@v4
        with:
          node-version: '18'

- name: Install SafeClaw
        run: npm install -g @authensor/safeclaw

- name: Verify policy syntax
        run: safeclaw policy validate ./safeclaw-policy.json

- name: Run policy tests
        run: safeclaw policy test ./safeclaw-policy.json --test-file ./policy-tests.json

- name: Verify audit trail integrity
        run: safeclaw audit verify ./safeclaw-audit.ndjson

CI/CD Commands

| Command | Description |
|---------|-------------|
| safeclaw policy validate | Validates policy file syntax |
| safeclaw policy test --test-file | Runs action requests against policy and verifies expected outcomes |
| safeclaw audit verify | Verifies SHA-256 hash chain integrity |

Port Configuration

Default Port

SafeClaw uses port 3829 by default for the local server that handles approval queue webhooks and dashboard connections.

Custom Port

Set via configuration:

{
  "server": {
    "port": 4000,
    "host": "127.0.0.1"
  }
}

Or via environment variable:

SAFECLAW_PORT=4000 npx @authensor/safeclaw

Port Usage

| Port | Purpose |
|------|---------|
| 3829 (default) | SafeClaw local server — dashboard communication, approval queue |

The local server binds to 127.0.0.1 by default (localhost only). Change the host to 0.0.0.0 to accept connections from other machines in multi-agent deployments.

Multi-Agent Deployment

SafeClaw supports multiple AI agents connecting to a single SafeClaw instance.

Architecture

┌──────────┐  ┌──────────┐  ┌──────────┐
│  Claude  │  │  OpenAI  │  │LangChain │
│  Agent   │  │  Agent   │  │  Agent   │
└────┬─────┘  └────┬─────┘  └────┬─────┘
     │             │             │
     └─────────────┼─────────────┘
                   │
                   ▼
          ┌─────────────────┐
          │  SafeClaw Engine │
          │  (single instance)│
          └─────────────────┘

Agent Configuration

Register each agent in the configuration:

{
  "agents": {
    "claude-code": {
      "label": "Claude Code Agent",
      "enabled": true
    },
    "openai-gpt4": {
      "label": "OpenAI GPT-4 Assistant",
      "enabled": true
    },
    "langchain-researcher": {
      "label": "LangChain Research Agent",
      "enabled": true
    }
  }
}

Policy rules can target specific agents using the agent field in conditions. See the Integration Reference for provider-specific configuration and the Policy Rule Syntax for agent identity matching.

Scaling Considerations

Single-Machine Performance

A single SafeClaw instance handles typical agent workloads:

| Metric | Capacity |
|--------|----------|
| Policy evaluation throughput | Thousands of evaluations per second |
| Evaluation latency | Sub-millisecond (< 1ms) |
| Concurrent agents | Limited only by system resources |
| Policy size | Hundreds of rules with negligible performance impact |
| Audit trail size | Limited by disk space; NDJSON format supports efficient append |

When to Scale

SafeClaw's local execution model means the policy engine runs on the same machine as the agents. Scaling is typically achieved by deploying one SafeClaw instance per machine or container, not by scaling SafeClaw itself.

| Scenario | Approach |
|----------|----------|
| Multiple agents on one machine | Single SafeClaw instance (default) |
| Agents distributed across machines | One SafeClaw instance per machine |
| Containerized agents | One SafeClaw container per agent container (sidecar pattern) |
| Kubernetes deployment | SafeClaw as a sidecar container in each agent pod |

Policy Synchronization

In multi-machine deployments, the control plane (safeclaw.onrender.com) synchronizes policies across all instances. When a policy is updated via the dashboard, the change propagates to all connected SafeClaw instances at the configured sync interval.

Dashboard ──→ Control Plane ──→ SafeClaw Instance A
                             ──→ SafeClaw Instance B
                             ──→ SafeClaw Instance C

Uninstallation

npx (no installation to remove)

If SafeClaw was run via npx, no global installation exists. Remove local files:

rm safeclaw.config.json safeclaw-policy.json safeclaw-audit.ndjson .safeclaw-key

Global Installation

npm uninstall -g @authensor/safeclaw

Related References

• Dashboard and API Reference — Setup wizard and dashboard features
• Security Model Reference — Local execution and control plane boundaries
• Integration Reference — Connecting agents to SafeClaw
• Policy Rule Syntax Reference — Policy file format
• Simulation Mode Reference — Recommended starting mode for new deployments
• Test Coverage Reference — Quality assurance verification