Setup Guide

Prerequisites

• Node.js 22 or later
• npm (included with Node.js)

Installation

git clone <repo-url> clauth
cd clauth
npm install

Initialize

npm run cli -- init

This creates ~/.clauth/ with all necessary state files and prompts for a vault passphrase (minimum 12 characters).

Custom transport

TCP (default):

npm run cli -- init --transport tcp --host 127.0.0.1 --port 4317

Unix socket:

npm run cli -- init --transport unix --socket "$HOME/.clauth/clauth.sock"

Store Credentials

Set the passphrase (or use CLAUTH_PASSPHRASE_FILE):

export CLAUTH_PASSPHRASE='your-long-passphrase-here'

Store a GitHub token:

npm run cli -- store --handle github-main --provider github --secret ghp_xxx

Store with metadata (auth type, custom host policy):

npm run cli -- store --handle custom-api --provider custom --secret sk_xxx \
  --metadata authType=bearer,allowedHosts=api.custom.example.com

Store with TTL (auto-expiry):

npm run cli -- store --handle temp-token --provider github --secret ghp_yyy --ttl 3600

Grant Skill Access

npm run cli -- grant --skill my-agent --provider github --scope github:read --rpm 60

Scope format is provider:action. Wildcards supported:

• github:* — all actions on GitHub
• *:read — read on any provider

Rate limit (--rpm) defaults to 60 requests/minute per grant.

Issue Skill Tokens

Skills authenticate via tokens issued by an admin:

npm run cli -- skill-token issue --skill my-agent

Save the token — it is shown only once. Skills include it as x-clauth-skill-token header.

Start the Daemon

Development mode (TypeScript strip):

export CLAUTH_PASSPHRASE='your-long-passphrase-here'
export CLAUTH_ADMIN_TOKEN='set-admin-token'
npm run dev

Production mode (compiled):

npm run build
export CLAUTH_PASSPHRASE='your-long-passphrase-here'
export CLAUTH_ADMIN_TOKEN='set-admin-token'
npm start

The daemon listens on http://127.0.0.1:4317 by default.

Verify Setup

npm run cli -- doctor

Check daemon health:

curl http://127.0.0.1:4317/health

View status:

npm run cli -- status

Configure Alert Webhooks

Edit ~/.clauth/config.json:

{
  "alertChannels": [
    {
      "type": "webhook",
      "url": "https://hooks.slack.com/services/xxx",
      "minSeverity": "warning"
    }
  ]
}

Test delivery:

curl -X POST http://127.0.0.1:4317/clauth/v1/admin/alerts/test \
  -H "x-clauth-admin-token: $CLAUTH_ADMIN_TOKEN" \
  -H "content-type: application/json" \
  -d '{"url": "https://hooks.slack.com/services/xxx"}'

Configure Advisory Feeds

Edit ~/.clauth/config.json:

{
  "advisoryFeeds": [
    {
      "name": "github",
      "url": "https://api.github.com/advisories",
      "type": "github"
    }
  ],
  "advisoryPollIntervalMs": 3600000
}

On critical advisory matching a stored provider, clauth auto-revokes grants and deletes affected credentials.

Docker Deployment

docker build -t clauth .

Or use Docker Compose:

# Create .env file
echo "CLAUTH_PASSPHRASE=your-long-passphrase-here" > .env
echo "CLAUTH_ADMIN_TOKEN=set-admin-token" >> .env

docker compose up -d

The compose file mounts ~/.clauth as a volume and runs the container as a non-root user with a read-only filesystem.

systemd Service

# Generate the service file
npm run cli -- service install --target systemd

Review and edit the generated env file
~/.clauth/clauth.env contains CLAUTH_PASSPHRASE and CLAUTH_ADMIN_TOKEN placeholders

Copy to systemd directory
npm run cli -- service apply --target systemd --write true

Or apply and start (requires --ackSystem for system-level commands)
npm run cli -- service apply --target systemd --write true --run true --sudo true --ackSystem true

launchd Service (macOS)

npm run cli -- service install --target launchd
npm run cli -- service apply --target launchd --write true

OpenClaw Migration

Import credentials from an existing OpenClaw configuration:

# Dry run — shows what would be migrated
npm run cli -- migrate

From a custom path
npm run cli -- migrate --from /path/to/openclaw.json

Write mode — stores credentials and rewrites config
npm run cli -- migrate --write

The original config is backed up before rewriting. Secret values are replaced with clauth://handle references.

Environment Variables