Install

Choose a path

For an ordinary agent on macOS, Linux, or Windows, use the core install and quickstart. Fleet stays off, and the separate C daemon is not installed.

For a Linux device without a Fleet gateway, use the local-only smoke below. It builds the MINIMAL development profile, runs the C tests, and needs no broker, certificates, or Fleet API token. The policy compiler test needs Python 3 and PyYAML. Use the production build and deployment steps later on this page when connecting real devices to Fleet.

For an optional Fleet deployment, install the core gateway first, run defenseclaw setup edge-connector on the gateway host, then provision an authenticated TLS broker with per-device topic ACLs and registration-issued device keys before starting Linux C devices. The wizard saves the API token, signing keys, and selected registration endpoint before enabling Fleet. On Linux it also provisions the local C service's environment through sudo; on macOS and Windows it configures the gateway only. The C daemon itself runs on Linux. CLI health and policy commands use the configured local gateway; --endpoint is used by device installation and registration.

Local-only Linux smoke

Install Git, a C compiler, CMake 3.22+, Make, Python 3, and PyYAML before running the commands below.

git clone https://github.com/cisco-ai-defense/defenseclaw.git
cd defenseclaw
cmake -S edge-connector -B edge-connector/build-local \
  -DDCLAW_PROFILE=MINIMAL -DDCLAW_DEV_MODE=ON
cmake --build edge-connector/build-local -j2
ctest --test-dir edge-connector/build-local --output-on-failure
./edge-connector/build-local/edge-connector --help

This checks the local C engine and binary without enabling the gateway or installing a service. The MINIMAL profile has no MQTT; use STANDARD or EDGE with TLS and keys for Fleet devices.

Build a Linux Fleet device from source

Required: gcc, cmake (3.22+), make, and mbedTLS 3.x development libraries for production MQTT over TLS.

git clone https://github.com/cisco-ai-defense/defenseclaw.git
cd defenseclaw/edge-connector
mkdir build && cd build
cmake .. -DDCLAW_PROFILE=STANDARD -DDCLAW_DEV_MODE=OFF -DDCLAW_ALLOW_HMAC_OTA=ON
make -j$(nproc)

Run tests

ctest --output-on-failure

Run the unit and acceptance suites for your selected build profile. The exact test count may change as suites are added.

Install system-wide

sudo make install

CMake installs the binary and support files. For a managed Linux service, also install the shipped systemd unit and provision its required environment file as shown in the repository installation guide.

Build profiles

cmake .. -DDCLAW_PROFILE=MINIMAL   # no MQTT; constrained builds
cmake .. -DDCLAW_PROFILE=STANDARD  # Raspberry Pi, Jetson, SBCs
cmake .. -DDCLAW_PROFILE=EDGE      # edge gateways with bloom filter

Binary size depends on the target toolchain, linked TLS libraries, and build flags. Measure the installed binary for your target.

Configure the policy

Step 1 — Copy and edit

# Return to the repository root (if you are still in edge-connector/build)
cd ../..

mkdir -p ~/.defenseclaw
cp edge-connector/policies/strict.yaml ~/.defenseclaw/policy.yaml

Edit ~/.defenseclaw/policy.yaml:

name: my-device-policy
version: 1

skill_actions:
  critical:
    runtime: disable    # BLOCK
  high:
    runtime: disable    # BLOCK
  medium:
    runtime: warn       # WARN (allow but log)

iot_extensions:
  capability_sequences:
    - sequence: [net_fetch, exec_shell]
      action: block
    - sequence: [net_fetch, actuate]
      action: block

  destination_allowlist:
    - "1.1.1.1" # illustrative public IP; replace with one approved for your service

Step 2 — Check built-in protection

Content patterns, rate limits (60 tool calls, 30 network requests, 10 actuations per minute), and the SSRF guard are built into this C release. The policy compiler rejects unsupported content_inspection, ssrf_protection, custom regex, destination_denylist, rate_limits, and escalation_mode settings. Production uses synchronous Fleet escalation by default; OTA policy cannot change this mode. Network tools require a nonempty destination. Hostnames, private IPs, and numeric aliases are blocked across profiles; an approved destination must be a canonical public IPv4 or bracketed globally scoped IPv6 literal in destination_allowlist. The parser does not prove external routability. Replace the illustrative 1.1.1.1 address with the approved endpoint for your service.

Step 3 — Compile (optional)

Only needed when you change the policy. Pre-built binaries include the default policy.

The compiler needs Python 3 and PyYAML. CMake installs the script but does not install its Python dependency. A raw release tar needs provisioned Python 3 and PyYAML before Fleet policy push. Linux enterprise RPM/DEB leaves them optional while Fleet is off; provision trusted /usr/bin/python3 and distro PyYAML before enabling Fleet. Managed install/ensure checks the prerequisite before service changes. Per-user installers use their bundled Python environment. A managed macOS .pkg with Fleet enabled requires PyYAML 6.0.3 inside a trusted Python.org framework interpreter (3.10–3.14). For example, check /Library/Frameworks/Python.framework/Versions/3.13/bin/python3.13 -I -c 'import yaml; print(yaml.__version__)'. The interpreter, framework parents, and PyYAML package tree must be root-owned and not group/world-writable; managed install/ensure refuses Fleet-enabled config if none of the trusted candidates passes. Apple's /usr/bin/python3 and Homebrew PATH are not selected for this channel. Managed Windows standalone Setup carries the compiler in its signed Setup payload and activates it only for authenticated Fleet-enabled config, using the admitted Python/PyYAML scanner runtime. Fleet-off Setup/upgrade leaves no active compiler; disabling Fleet removes a previous active script. Managed Secure Client profiles on macOS and Windows reject Fleet-enabled configuration because they do not ship this compiler/runtime.

Fleet is an optional gateway subsystem. Managed Linux/macOS packages carry the compiler as inert source under <InstallRoot>/share/fleet/; validated Fleet-enabled install/ensure copies it into the protected <InstallRoot>/lib/defenseclaw/ path. Fleet-off install/upgrade does not activate the compiler or need Python/PyYAML. A Fleet-off raw payload install discards its optional compiler source; provide the staged release --payload to enable Fleet later. The local observability bundle includes an empty Fleet dashboard, but no Fleet scrape job runs by default.

Standard per-user install.sh/install.ps1 leave Fleet off and copy the matching compiler only when the existing config explicitly enables it. defenseclaw setup edge-connector installs the optional compiler and enables fleet.enabled only after credential setup succeeds. The core gateway installer does not install or start the separate C Edge Connector service.

cd edge-connector
python3 tools/policy_compiler.py \
  --input ~/.defenseclaw/policy.yaml \
  --profile standard --version 1 \
  --output-header generated/policy_tables.h \
  --output-binary dist/policy.bin

The command's binary output has a development stub signature when no signing key is supplied; production devices will reject it as an OTA update. Use the Fleet policy-push API with matching DCLAW_OTA_HMAC_KEY secrets to compile and sign production OTA updates. The compiler's Ed25519 --signing-key output is not accepted by this C receiver.

Integrate with your AI agent

The Edge Connector is framework-agnostic. Choose the integration that matches your stack.

Generic Python adapter (recommended)

The simplest starting point for any Python agent. Three lines to add security enforcement:

When using the source checkout, run your agent with PYTHONPATH=/path/to/defenseclaw/edge-connector/tools; after sudo make install, use the installed adapter directory (normally /usr/local/lib/defenseclaw). CMake copies the Python files there but does not add that directory to Python's import path. Set DCLAW_LIB_PATH if your shared library is not at /usr/local/lib/libdclaw_core.so.

from generic_hook import EdgeConnector

ec = EdgeConnector()  # auto-detects FFI or Unix socket

verdict = ec.evaluate(
    tool_name="exec_shell",
    arguments={"command": "rm -rf /"},
)
if verdict.blocked:
    print(f"Blocked: {verdict.reason}")

Uses the Unix socket first when the daemon is running, then FFI (ctypes) when no daemon is available. The adapter fails closed if the engine is unavailable. In production, DCLAW_FAIL_OPEN=1 also requires an authorized DCLAW_FAIL_OPEN_TOKEN tied to DCLAW_AUDIT_KEY; the flag alone does not enable fail-open.

MCP proxy (Model Context Protocol)

A transparent MCP proxy that sits between an LLM client (Claude, Codex, etc.) and a real MCP server. Intercepts every tools/call request and evaluates it through the C engine's local guards, verdict cache, and optional Fleet escalation. All other MCP messages pass through unchanged.

LLM Client (Claude, Codex)
    | MCP (stdio / HTTP)
    v
Edge Connector MCP Proxy
    | evaluates via EdgeConnector.evaluate()
    | MCP (stdio / HTTP)
    v
Real MCP Server (ESP-Claw, HA-MCP, etc.)

From the edge-connector/ source directory, quick start with a local stdio MCP server:

DCLAW_MCP_UPSTREAM='["python3", "-m", "esp_claw.mcp_server"]' \
  python3 tools/mcp_proxy.py

With a config file:

python3 tools/mcp_proxy.py --config tools/mcp_proxy_config.yaml

Use stdio for a local MCP server: the proxy rejects private and loopback HTTP upstream addresses. For a remote upstream, configure a reviewed public HTTPS endpoint and verify its downstream network behavior.

Use with Claude Desktop or Claude Code by adding the proxy to your MCP client config:

{
  "mcpServers": {
    "esp-claw-secured": {
      "command": "python3",
      "args": ["/usr/local/lib/defenseclaw/mcp_proxy.py"],
      "env": {
        "DCLAW_MCP_UPSTREAM": "[\"python3\", \"-m\", \"esp_claw.mcp_server\"]",
        "DCLAW_LIB_PATH": "/usr/local/lib/libdclaw_core.so"
      }
    }
  }
}

Replace /usr/local/lib if CMake installed into another library directory. The named upstream module, esp_claw.mcp_server, must be installed separately; substitute your actual stdio MCP server command.

Environment variables: DCLAW_MCP_UPSTREAM (target command or URL), DCLAW_MCP_TRANSPORT (stdio or http), DCLAW_MCP_PORT (default 8089). All standard Edge Connector env vars are passed through.

LangChain / LangGraph

Wrap LangChain tools so every invocation passes through the Edge Connector:

from langchain_hook import wrap_tools

tools = wrap_tools(my_tools)
agent = create_react_agent(llm, tools)

Or use as a LangGraph node:

from langchain_hook import edge_connector_node

graph.add_node("security_gate", edge_connector_node)
graph.add_edge("agent", "security_gate")
graph.add_edge("security_gate", "tools")

HTTP middleware (FastAPI / Flask)

For agents that expose tool execution via HTTP APIs:

# FastAPI
from http_middleware import EdgeConnectorMiddleware
app.add_middleware(EdgeConnectorMiddleware)

# Flask
from http_middleware import flask_edge_connector
flask_edge_connector(app)

Intercepts POST requests to tool-execution endpoints and returns 403 for blocked calls.

PicoClaw

PicoClaw integrates via its process hook system:

mkdir -p ~/.picoclaw/hooks
cp /usr/local/lib/defenseclaw/picoclaw_hook.py ~/.picoclaw/hooks/defenseclaw_gate.py
picoclaw config edit

Add to hooks.processes:

{
  "defenseclaw_gate": {
    "enabled": true,
    "priority": 5,
    "transport": "stdio",
    "command": ["python3", "/home/USERNAME/.picoclaw/hooks/defenseclaw_gate.py"],
    "env": {
      "DCLAW_LIB_PATH": "/usr/local/lib/libdclaw_core.so",
      "DCLAW_LOG_PATH": "/home/USERNAME/edge-connector.log"
    },
    "intercept": ["before_tool", "before_llm", "after_llm"]
  }
}

Replace USERNAME with the real home directory. Process launchers do not necessarily expand ~ in JSON command or environment values.

What gets intercepted

Verify

# Check that the hook protocol responds (this does not evaluate a tool)
echo '{"jsonrpc":"2.0","id":1,"method":"hook.hello","params":{}}' | \
  DCLAW_LIB_PATH=/usr/local/lib/libdclaw_core.so \
  python3 ~/.picoclaw/hooks/defenseclaw_gate.py

# Observe a sensor-read decision; production waits for a Fleet verdict
picoclaw agent -m "check battery status"

# Observe a shell decision; inspect the actual tool call and audit result
picoclaw agent -m "run whoami in the shell"

# Watch decisions
tail -f ~/edge-connector.log

Low-level: shared library (FFI)

Load libdclaw_core.so from any language that supports C FFI:

import ctypes
lib = ctypes.CDLL("/usr/local/lib/libdclaw_core.so")
# Call dclaw_evaluate() — see defenseclaw.h for struct definitions

Low-level: Unix socket (JSON-RPC)

Query the daemon from any process:

tool_hash="$(printf exec_shell | sha256sum | cut -d' ' -f1)"
printf '{"jsonrpc":"2.0","id":1,"method":"evaluate","params":{'\
'"tool_name":"exec_shell","tool_hash":"%s","capabilities":4,'\
'"destination":"","session_id":1}}\n' "$tool_hash" | \
  socat - UNIX-CONNECT:/run/defenseclaw/defenseclaw.sock

This optional raw IPC probe requires socat and a running daemon. The daemon derives trusted capability flags from the tool name; the caller-supplied capabilities value is not authority.

Tool-to-capability mapping

Each tool must map to a capability that determines how the Edge Connector handles it.

Production strict mode waits for a Fleet verdict on an uncached undecided call and blocks when the gateway is unavailable, including for read-only tools. DCLAW_STRICT_MODE=0 explicitly permits speculative execution only for the first four capabilities when the build supports it. A destination allowlist entry does not itself approve a tool call.

MQTT broker setup

The Edge Connector uses MQTT 3.1.1 for verdict escalation (device to gateway) and signed policy/emergency distribution (gateway to device). Any standards-compliant broker works; Eclipse Mosquitto is recommended for simplicity.

Anonymous local test with Docker:

Mosquitto 2.x defaults to local-only mode (no remote connections). You must mount a config file that binds to 0.0.0.0:

# Create a minimal config that accepts remote connections
cat > mosquitto.conf <<'EOF'
listener 1883 0.0.0.0
allow_anonymous true
EOF
chmod 0644 mosquitto.conf

docker run -d --name mosquitto -p 127.0.0.1:1883:1883 \
  -v "$PWD/mosquitto.conf:/mosquitto/config/mosquitto.conf:ro" \
  eclipse-mosquitto:2

Authenticated local test setup:

This is an alternative to the preceding container. Stop and remove that disposable mosquitto container before running the authenticated example with the same name and port:

docker rm -f mosquitto 2>/dev/null || true

# Mosquitto's container runs as UID/GID 1883. Make its bind mount readable.
sudo install -d -o 1883 -g 1883 -m 0700 mqtt
docker run --rm -it --user 1883:1883 \
  -v "$PWD/mqtt:/mosquitto/config" --entrypoint mosquitto_passwd \
  eclipse-mosquitto:2 -c /mosquitto/config/passwd dclaw

# Create a config that requires authentication
sudo tee mqtt/mosquitto.conf >/dev/null <<'EOF'
listener 1883 0.0.0.0
allow_anonymous false
password_file /mosquitto/config/passwd
EOF
sudo chown 1883:1883 mqtt/mosquitto.conf
sudo chmod 0600 mqtt/mosquitto.conf mqtt/passwd

docker run -d --name mosquitto -p 127.0.0.1:1883:1883 \
  -v "$PWD/mqtt:/mosquitto/config:ro" \
  eclipse-mosquitto:2

For this local test, set credentials on both sides using environment variables (the Go and C MQTT clients do not parse userinfo from the broker URL):

# Generate one nonzero test HMAC key; copy it securely to the device when it runs elsewhere.
export DCLAW_DEVICE_KEY="$(python3 -c 'import secrets; print(secrets.token_hex(32))')"

# Gateway (Go fleet server)
export DCLAW_DEV_MODE=ON # unmanaged local test only; production rejects zero-key mode
export DCLAW_MQTT_BROKER_URL=tcp://127.0.0.1:1883
export DCLAW_MQTT_USER=dclaw
export DCLAW_MQTT_PASS='<password entered above>'

# Edge devices (C edge connector)
export DCLAW_BROKER_URL=mqtt://127.0.0.1:1883
export DCLAW_MQTT_USER=dclaw
export DCLAW_MQTT_PASS='<password entered above>'

Configure the gateway (Go fleet server):

export DCLAW_MQTT_BROKER_URL=tcp://127.0.0.1:1883

Configure edge devices (C edge connector):

export DCLAW_BROKER_URL=mqtt://127.0.0.1:1883

Both sides must point to the same broker. Enable the Fleet subsystem explicitly in ~/.defenseclaw/config.yaml:

fleet:
  enabled: true
  mqtt_broker_url: tcp://127.0.0.1:1883 # local test only

The gateway publishes policy updates; devices publish heartbeats and escalation requests. Use per-device broker topic ACLs, because the gateway subscriber cannot infer a verified publisher ClientID from an MQTT PUBLISH packet.

Upgrade together: Heartbeat and registration messages now carry a durable 4-byte boot counter and 4-byte last-applied emergency sequence. Keyed C devices send a 40-byte payload plus a 32-byte HMAC (72 bytes total); the gateway rejects older 64- and 68-byte signed frames. Upgrade the Edge Connector on each device with the Fleet gateway, and confirm heartbeats resume before relying on device status or policy distribution. The gateway replays missed emergency commands in signed predecessor order from durable history, up to 32 per signed registration or heartbeat; later heartbeats request the next page. A history gap or unavailable durable store fails closed. Broker publication alone does not prove device application.

Legacy flash partitions with unsigned policy payloads are preserved but refused at boot, including in a development build. Back up the device state and use a trusted re-sign/reprovisioning procedure before starting the new connector. An in-place metadata migration alone does not make the old policy executable; verify the signed flash policy and authenticated heartbeat after upgrade.

The gateway rejects missing or invalid device HMAC keys by default. Pre-register every production device through the authenticated Fleet API; MQTT auto-registration is for unmanaged local development only. An unmanaged development host can opt into the legacy zero-key behavior only with DCLAW_DEV_MODE=ON; managed deployments never permit that fallback. For multiple devices, use registration-issued per-device keys rather than the one shared test key above. The C device binds its durable emergency sequence to tenant/fleet identity; moving it requires trusted flash reset and reprovisioning, because a new identity with the prior emergency state refuses startup.

Environment variables

Server-side (Go fleet gateway)

Device-side (C edge connector and Python hooks)

Compile-time constants

Set in CMakeLists.txt; changing these requires rebuilding the C library:

Grafana dashboard

The Fleet dashboard is provisioned with the bundled local observability stack. Its source JSON is at edge-connector/dashboards/fleet-dashboard.json. It shows registered device status, heartbeats, block and allow verdicts, Fleet alerts, cache activity, and rollback counters. The dashboard is empty until Prometheus scrapes the authenticated Fleet metrics endpoint.

Fleet is disabled by default. Enable fleet.enabled: true on the gateway and set its admin DCLAW_FLEET_API_TOKEN in the environment. The bundled Prometheus intentionally has no Fleet scrape target until you opt in, because the gateway API normally listens only on 127.0.0.1:18970 and containers cannot reach that address through the Linux host gateway. Tenant-scoped tokens cannot scrape global Fleet metrics.

For a local Docker stack, enable the optional scrape after confirming host.docker.internal:18970 reaches your gateway from a container. Docker Desktop on macOS provides this host name. On Linux, set gateway.api_bind to the Docker bridge's host IP only if your firewall restricts access to the Docker network; this changes the bind for the entire gateway REST API. Managed enterprise installs require loopback and cannot use that bind change. For those hosts, run Prometheus on the host or provide a separately secured metrics-only proxy. Keep the gateway API bearer token secret and use TLS for any nonlocal access.

cd bundles/local_observability_stack
test -n "$DCLAW_FLEET_API_TOKEN" || { echo 'Fleet API token is empty' >&2; exit 1; }
install -d -m 0700 "$HOME/.defenseclaw/fleet-secrets"
printf '%s' "$DCLAW_FLEET_API_TOKEN" > "$HOME/.defenseclaw/fleet-secrets/metrics-token"
chgrp "$(id -g)" "$HOME/.defenseclaw/fleet-secrets/metrics-token"
chmod 0640 "$HOME/.defenseclaw/fleet-secrets/metrics-token"
cp prometheus/examples/fleet.yml prometheus/scrape.d/fleet.yml
chmod 0755 prometheus/scrape.d
chmod 0644 prometheus/scrape.d/fleet.yml # Prometheus runs as a non-root user
export FLEET_METRICS_TOKEN_FILE="$HOME/.defenseclaw/fleet-secrets/metrics-token"
export FLEET_METRICS_TOKEN_GID="$(id -g)"
docker compose -f docker-compose.yml -f docker-compose.fleet.yml up -d

Keep the private fleet-secrets directory outside the bundle so wheel staging and bundle upgrades cannot copy the token. The token file needs group-read permission because the Prometheus container runs as a non-root user; the optional Compose file grants only this file's group to that container. Verify Status → Targets in Prometheus at http://127.0.0.1:9090/targets: defenseclaw-fleet must be UP. A 401 means the token is wrong; connection refused means the gateway bind/target is unreachable. Remove prometheus/scrape.d/fleet.yml and restart Compose to disable the scrape. When using another Prometheus instance, import the JSON and point its defenseclaw-prometheus data source at that instance. On an existing managed stack, the normal refresh preserves Grafana and Prometheus operator configuration; use --refresh-config only after backing up custom files, or copy the Fleet dashboard and scrape settings into the installed bundle by hand.

Benchmark

cd edge-connector/build
./tests/bench_latency

Measure latency and throughput on your own target hardware and selected build profile.

Troubleshooting