clawshell
clawshell
Security-privileged runtime control layer that protects PII and credentials for Hermes Agent.
Repository last updated Jul 13, 2026
Overview
ClawShell is a security-privileged process that acts as a safety harness for the Hermes Agent ecosystem. It sits between the agent and upstream LLM providers, intercepting requests to swap virtual API keys for real credentials stored in a protected directory. This ensures the agent never has direct access to sensitive keys or PII.
The system performs Data Loss Prevention (DLP) scanning on request and response bodies, redacting or blocking sensitive data like SSNs and credit card numbers using configurable regex patterns. It also provides secure email isolation via IMAP sender filtering, and supports OAuth-based authentication for providers like OpenAI's Codex/ChatGPT.
ClawShell is designed for operators who need a lightweight, Rust-based sidecar that enforces a strong security boundary without external dependencies. It runs in under 10MB of memory and integrates seamlessly with Hermes Agent through an interactive onboarding wizard.
Highlights
- Maps virtual keys to real credentials in protected Unix directories
- Scans and redacts PII in request/response bodies via regex
- Enforces sender-based email filtering for secure mailbox access
- Supports OAuth device code flow for Codex/ChatGPT
- Exposes runtime statistics on a loopback-only admin endpoint
- Ultra-lightweight Rust binary with Tokio async runtime
Features
API Token Secure Binding
Maps virtual API keys to real provider keys so Hermes Agent never holds real credentials. Real keys are stored in /etc/clawshell/clawshell.toml, readable only by the clawshell system user.
PII Safety Net (DLP)
Scans HTTP request and response bodies for sensitive data using configurable regex patterns. Matches can be redacted or the request blocked entirely.
Sensitive Email Isolation
Provides sender-based email filtering so each virtual key only sees mailbox content based on allow/deny rules. IMAP credentials are stored securely.
OAuth Authentication (Codex/ChatGPT)
Supports device code flow for OAuth-based authentication. Tokens are refreshed automatically and requests are translated to the ChatGPT Responses API format.
Runtime Statistics
Exposes counters at GET /admin/stats for auditing proxy activity, including requests protected, token usage, and filtered senders. Data is persisted to disk.
Seamless Integration
Drop-in sidecar configured via the onboard wizard. Uses Unix file system permissions for secret protection—no external key management service required.
Installation
Commands are reproduced exactly as published by the project maintainers. Always check the upstream repository for the current instructions.
cargo install clawshell --locked
# Requires privilege to set up the security boundary
sudo clawshell onboardnpm install -g @clawshell/clawshell
# Requires privilege to set up the security boundary
sudo clawshell onboardRUSTFLAGS="--remap-path-prefix=$(pwd)=. --remap-path-prefix=$HOME=/" cargo build --release
ls -al target/release/clawshellwget https://musl.cc/x86_64-linux-musl-cross.tgz -O /tmp/musl-cross.tgz
tar -xzf /tmp/musl-cross.tgz -C /tmp
CARGO_TARGET_X86_64_UNKNOWN_LINUX_MUSL_LINKER="/tmp/x86_64-linux-musl-cross/bin/x86_64-linux-musl-gcc" \
RUSTFLAGS="--remap-path-prefix=$(pwd)=. --remap-path-prefix=$HOME=/" \
cargo build --release --target x86_64-unknown-linux-muslRequirements
- Unix-like operating system (Linux/macOS)
- Rust toolchain (for building from source) or npm (for prebuilt binaries)
- sudo access for onboarding and daemon management
- Hermes Agent or OpenClaw installed (for integration)
How it's built
ClawShell is written in Rust and uses the Tokio async runtime. The repository is organized with source code under src/, including modules for DLP scanning (src/dlp.rs), email handling (src/email.rs), key management (src/keys.rs), OAuth (src/oauth/), and configuration migration (src/migration/).
The binary is distributed via Cargo (cargo install clawshell) and npm (@clawshell/clawshell). It listens by default on 127.0.0.1:18790 and reads configuration from /etc/clawshell/clawshell.toml. Real credentials are stored in this directory with Unix permissions 700, readable only by the clawshell system user.
ClawShell integrates with Hermes Agent by patching its configuration to route requests through the proxy. The onboard wizard sets up the security boundary, generates virtual keys, and starts the daemon. The admin statistics endpoint is loopback-only and persists counters to disk every 30 seconds.
Source
This summary was written for Neura Market from the project's own repository. Install commands, identifiers and licence details are reproduced unchanged. The clawshell/clawshell repository is the authoritative source and the place to file issues or contribute.
Category: Security & Privacy · Licensed under Apache-2.0