SecureClaw

Download the binary from the download page, make it executable, and run the onboarding wizard:

chmod +x secureclaw-linux-amd64
sudo mv secureclaw-linux-amd64 /usr/local/bin/secureclaw
secureclaw onboard

The wizard walks you through everything: provider selection, API key, security level, vault password, and your AI's name/personality. Takes about 2 minutes.

secureclaw start

This runs attestation, decrypts the vault, and starts the gateway. Open http://localhost:18789 in your browser to chat.

You'll be asked for your vault password on startup. The password is used to decrypt your secrets, then wiped from memory.

secureclaw stop

Stops all active agent sessions. You can also type /stop in the chat UI, or send SIGUSR1 to the process.

~/.secureclaw/
  config.yaml          # main configuration
  secrets.age          # encrypted vault
  SOUL.md              # AI personality / system prompt
  chrome-profile/      # persistent browser profile
  skills/              # signed skill bundles
  logs/
    audit.jsonl        # append-only audit log
  sessions/
    *.jsonl            # conversation history (one per session)

Session files are created with 0600 permissions (owner read/write only). The audit log is append-only and records every tool call and confirmation decision.

Start the gateway server. Runs attestation, unlocks the vault, loads your config and SOUL.md, and starts listening for connections.

Default port: 18789. Change it in config.yaml under gateway.port.

Interactive first-run setup wizard. Configures your provider, API key, security level, vault password, email (optional), and AI personality.

You can re-run this anytime to change settings. Your existing vault is preserved.

Store a secret in the encrypted vault. The value is encrypted with age and never written to disk in plain text.

secureclaw secrets set ANTHROPIC_API_KEY sk-ant-...

Retrieve a secret from the vault. Prints the decrypted value to stdout. The key material is wiped from memory after retrieval.

Add a messaging channel integration. Supported channels: telegram, slack, discord, whatsapp, matrix, signal.

secureclaw channels add telegram

List all configured channel integrations and their status.

Remove a channel integration. This removes the channel config but doesn't delete any messages.

Check for updates and apply them. The new binary is verified via attestation before replacing the old one.

Stop all active agent sessions. Also works via /stop in chat or SIGUSR1/SIGUSR2 signals.

Config lives at ~/.secureclaw/config.yaml. Created by the onboarding wizard. You can edit it directly, but never put secrets in the config. SecureClaw will reject any config that contains API keys, tokens, or passwords.

Configure which LLM to use:

provider:
  name: anthropic    # anthropic | openai | openrouter | ollama | groq | zai | minimax
  model: claude-opus-4-6
  max_tokens: 8192
  fallbacks:
    - name: openrouter
      model: anthropic/claude-sonnet-4-6

API keys go in the vault, not the config: secureclaw secrets set ANTHROPIC_API_KEY sk-ant-...

gateway:
  host: "127.0.0.1"
  port: 18789
  tls: false
  origin_allowlist:
    - "localhost"
    - "127.0.0.1"

origin_allowlist controls which origins can connect via WebSocket. Keep this tight. Only add origins you trust.

Controls how tool calls are authorized:

execution:
  mode: confirm      # confirm | allowlist | dangerous | smart
  allowlist:
    - "shell.run: git *"
    - "files.read: *"

• confirm — asks you before every tool call (safest)
• allowlist — auto-approves matching patterns, confirms the rest
• smart — scans file paths and content for sensitive patterns, auto-approves safe ones
• dangerous — auto-approves everything except the hard blocklist (dev only, don't use in production)

attestation:
  level: maximum     # maximum | standard | minimal
  worker_url: "https://hwweb.uk"
  website_url: "https://secureclaw-website.pages.dev"

• maximum — dual-source verification (Worker + Website), vault fragment from both
• standard — single-source verification (Worker only)
• minimal — hash-only check, no vault fragment (dev use)

agent:
  default: claude-opus-4-6
  compaction_threshold: 0.8

compaction_threshold controls when conversation history gets compressed. At 0.8, compaction triggers when context usage hits 80% of the model's limit.

browser:
  chrome_path: ""         # auto-detected if empty
  search_engine: "google"

SecureClaw can browse the web via headless Chrome. It auto-detects Chrome/Chromium on your system. Set chrome_path if auto-detection fails.

email:
  imap_host: "imap.gmail.com"
  imap_port: "993"
  smtp_host: "smtp.gmail.com"
  smtp_port: "587"
  poll_interval: "3m"
  queue_size: 100

Email credentials go in the vault: secureclaw secrets set EMAIL_PASSWORD ...

logging:
  level: info     # debug | info | warn | error
  file: ""        # empty = stderr only

Audit logs (tool calls, confirmations) are always written to ~/.secureclaw/logs/audit.jsonl regardless of this setting.

~/.secureclaw/SOUL.md is your AI's system prompt. It defines the personality, tone, and behavior. Think of it as the AI's identity file.

The onboarding wizard creates a default one based on the name you choose. You can edit it anytime. Changes take effect on the next session.

Keep it focused. A good SOUL.md includes:

• Name and role — "You are Atlas, a security-focused development assistant"
• Tone — casual, formal, technical, friendly, whatever you want
• Boundaries — what should the AI refuse to do?
• Preferences — coding style, language, frameworks you use

SecureClaw automatically appends a prompt injection mitigation footer to your SOUL.md. You don't need to add your own.

# Atlas

You are Atlas, a security-focused AI assistant.

## Personality
- Direct and concise. No fluff.
- When in doubt, ask. Don't guess.
- Explain security implications of any action.

## Coding preferences
- Go for backend, TypeScript for frontend
- Always run tests before committing
- Prefer stdlib over dependencies

## Boundaries
- Never commit secrets to git
- Never run commands as root
- Ask before deleting any files

shell.run executes commands in your system shell. Every command goes through the tool interceptor. The hard blocklist prevents obviously dangerous commands (rm -rf /, sudo, pipe-to-shell, etc.) even in dangerous mode.

files.read, files.write, files.list. All file operations are sandboxed to your workspace directory. Symlinks pointing outside the sandbox are blocked. Sensitive paths (~/.ssh, ~/.aws, .env, *.pem, *.key) are blocked by default.

browser.navigate, browser.interact, browser.wait. Uses headless Chrome. The browser can search the web, read pages, fill forms, and take screenshots. Cookies persist in ~/.secureclaw/chrome-profile/.

email.send, email.read, email.search. Connects via IMAP/SMTP. Credentials stored in the vault. The AI can read, search, and send emails on your behalf (with your confirmation in confirm mode).

SecureClaw can connect to multiple messaging platforms:

• Telegram — bot token via BotFather
• Slack — app token with socket mode
• Discord — bot token with message content intent
• WhatsApp — via WhatsApp Business API
• Matrix — any homeserver, uses access token
• Signal — via signal-cli REST sidecar

All channel tokens go in the vault. The config only stores non-secret settings like homeserver URLs.

secureclaw channels add telegram

This prompts you for the bot token (stored in vault) and any channel-specific config. You can also set an allowlist of sender IDs to restrict who can talk to your assistant.

channels:
  permissions:
    master_channel: telegram
  telegram:
    accounts:
      main:
        allowlist: ["123456789"]
        pairing: true

master_channel sets which channel gets tool confirmation requests. allowlist restricts who can message the bot. pairing allows new users to pair via DM.

Skills are signed bundles that extend what SecureClaw can do. Each skill has a capability manifest declaring what tools it needs access to. Skills are signed with Ed25519, so tampered skills won't load.

Skills live in ~/.secureclaw/skills/. Drop a signed skill bundle in that directory and restart. SecureClaw verifies the signature on load and rejects anything that doesn't check out.

A skill bundle is a directory with:

• manifest.yaml — declares name, version, description, and required capabilities
• prompt.md — the skill's system prompt, injected when the skill is activated
• signature — Ed25519 signature over the manifest + prompt

Sign your skills with the developer key generated during make dev-setup. The public key is embedded in the binary for verification.

Skills must declare which tools they need. The manifest lists capabilities like shell.run, files.read, files.write, browser.navigate, etc. A skill can only use the tools it declares. Anything else is blocked.

This means your binary's BLAKE3 hash doesn't match any registered release. Possible causes:

• Corrupted download — re-download from the download page and check the hash
• Custom build — only official releases are registered. Custom builds will always fail
• Network issue — attestation requires internet access to reach both the Worker and website

Wrong password, or the vault was created with a different security level:

• Wrong password — there's no password recovery. If you forgot it, you need to create a new vault
• Security level mismatch — a vault created at "maximum" needs the server fragment. You can't open it at "minimal" level
• Corrupted vault file — check ~/.secureclaw/secrets.age. If it's corrupted, you'll need to recreate it

Check these things:

• Origin mismatch — your browser's origin must be in gateway.origin_allowlist
• Port conflict — another process might be using port 18789. Check with lsof -i :18789
• TLS mismatch — if gateway.tls: true, you need to use https://

That's the default behavior in confirm mode. If you want to skip confirmation for safe commands, switch to allowlist or smart mode and add patterns:

execution:
  mode: allowlist
  allowlist:
    - "shell.run: git *"
    - "files.read: *"
    - "files.write: *.go"

Or click "yes always" in the confirm dialog to add a pattern for the current session.

SecureClaw scans your config for API keys, tokens, and passwords. If it finds anything that looks like a secret, it refuses to load. Move secrets to the vault:

secureclaw secrets set ANTHROPIC_API_KEY sk-ant-...
# then remove the key from config.yaml

Yes, the rate limiter has no loopback exemptions. This is intentional. If you're hitting rate limits during development, it usually means something is reconnecting in a loop. Check your client code.

Skills must be signed with a valid Ed25519 key. If the signature doesn't verify, SecureClaw silently skips the skill. Check:

• The signature file exists and is valid hex
• The manifest.yaml and prompt.md haven't been modified after signing
• The public key in the binary matches the private key used to sign