What the plugin is
A public, zero-LLM collector that turns runtime lifecycle and failure metadata into a small, versioned telemetry contract.
Sidewisp Plugin observes deterministic runtime facts, sanitizes them against a closed allowlist, stores pending events in an owner-only SQLite spool, and sends signed batches over HTTPS. OpenClaw runs it as a native background plugin, Hermes uses a per-user sidecar, and Codex plus Claude Code use documented command hooks.
The plugin contains no hosted dashboard, incident engine, alerting service, or autonomous remediation. Use Sidewisp's managed service, implement the compatible receiver protocol below, or generate your own operations stack from the public contract.
adaptersLifecycle + health facts
and spoolClosed schema + SQLite
and storeSigned HTTPS batches
and alertsAny compatible tools
Content-free
No prompts, responses, files, credentials, personal data, or tool payloads.
Durable
Pending events survive restarts and package upgrades in a bounded SQLite spool.
Inspectable
Read-only status and support methods expose health without exposing event content.
Portable
Versioned telemetry and receiver contracts keep storage and presentation replaceable.
Runtime coverage
Plugin v0.2.0 ships four collector adapters. Each declares its exact capabilities instead of pretending every runtime exposes the same hooks. Custom runtimes can implement the public adapter and telemetry contracts.
OpenClaw
Native background plugin with typed lifecycle/tool hooks, recovery, health, status, and support diagnostics.
SHIPPED IN V0.2.0Hermes Agent
Least-privileged per-user sidecar using the shared telemetry, spool, credential, and delivery contracts.
SHIPPED IN V0.2.0Codex
Stable command hooks cover sessions, turns, and tools. Provider failures remain an explicitly degraded capability.
CODEX CLI 0.145.0+Claude Code
Command hooks cover sessions, turns, tools, permission denials, and bounded provider/context failure classes.
CLAUDE CODE 2.1.218+Custom runtimes
Implement sidewisp.runtime-adapter.v1, declare every capability, and emit sanitized sidewisp.telemetry.v1 facts.
Install on OpenClaw
OpenClaw 2026.7.1+, Node.js 22.22.3+, outbound HTTPS, and a one-time token from Sidewisp or your compatible receiver are required. No sudo, inbound port, model provider, or LLM key.
Install an immutable release
openclaw plugins install git:github.com/golem-workers/[email protected] --force
openclaw plugins inspect sidewisp --runtime --jsonEnroll and verify
openclaw config set plugins.entries.sidewisp.config.setupToken sw_setup_REPLACE_ME
openclaw gateway restart
openclaw gateway call sidewisp.status --jsonThe setup token is exchanged once for a scoped installation credential and removed from active configuration. A healthy status reportsconfigured: true, installation state active, spool status healthy, uploader status idle orsent, and mode zero-llm.
Verify a release archive +
gh release download v0.2.0 \
--repo golem-workers/sidewisp-plugin \
--pattern '*.tgz' \
--pattern SHA256SUMS
sha256sum --check SHA256SUMS
gh attestation verify sidewisp-plugin-0.2.0.tgz \
--repo golem-workers/sidewisp-plugin
openclaw plugins install ./sidewisp-plugin-0.2.0.tgz --forceInstall on Hermes Agent
Hermes uses a user-owned sidecar on Linux or macOS until an equivalent stable native lifecycle is available.
Verify and unpack the release, then run the installer from its directory. Linux needs a systemd user session; macOS needs LaunchAgent support. Default installation never uses sudo.
SIDEWISP_ENDPOINT=https://api.sidewisp.com \
HERMES_SOURCE_DIR="$HOME/hermes-agent" \
./scripts/install-hermes.sh sw_setup_REPLACE_MECheck HTTPS endpoint, setup token shape, source directory, OS, and Node.js.
Create scoped credentials before installing any background service.
Stage immutable release, switch atomically, and start user service.
Inspect systemd or LaunchAgent state and metadata-only logs.
# Linux
systemctl --user status sidewisp-hermes-collector.service
journalctl --user -u sidewisp-hermes-collector.service --since today
# macOS
launchctl print "gui/$(id -u)/com.sidewisp.hermes-collector"Install on Codex
Codex CLI 0.145.0+, Node.js 22.22.3+, outbound HTTPS, and one setup token are required. Sidewisp observes sessions, turns, and local tool calls without reading content.
codex --version
codex features list | grep '^hooks '
SIDEWISP_ENDPOINT=https://api.sidewisp.com \
./scripts/install-codex.sh sw_setup_REPLACE_MEPreserve existing ~/.codex/hooks.json handlers and create a one-time backup.
Restart Codex, open /hooks, inspect the command, and trust its exact definition.
Each hook atomically writes one sanitized event into an owner-only inbox.
A detached zero-LLM worker spools and signs HTTPS batches without blocking Codex.
Covered hooks: SessionStart, SessionEnd,UserPromptSubmit, PreToolUse,PostToolUse, and Stop. Prompts, transcripts, assistant messages, tool arguments, and tool output are ignored. Only opaque IDs, tool name, outcome, and bounded scalar result metadata are eligible.
Install on Claude Code
Claude Code 2.1.218+, Node.js 22.22.3+, outbound HTTPS, and one setup token are required. The adapter covers lifecycle, tools, permission denials, and bounded provider failures.
claude --version
SIDEWISP_ENDPOINT=https://api.sidewisp.com \
./scripts/install-claude-code.sh sw_setup_REPLACE_MEMerge Sidewisp into ~/.claude/settings.json without replacing other hooks.
Map session, turn, tool, denial, and StopFailure events.
Ignore prompt, transcript, assistant text, tool payload, and raw error fields.
Keep events in local SQLite until a signed batch is acknowledged.
StopFailure retains only its documented class, such asrate_limit, authentication_failed,overloaded, or max_output_tokens.error_details and last_assistant_messagenever enter telemetry.
Privacy is structural
Only allowlisted fields survive sanitation. Unknown fields are discarded; malformed or unsafe allowlisted values are rejected before the spool.
- Runtime kind, version, and opaque instance ID
- Lifecycle and health event type
- Success, failure, degraded, or informational outcome
- Opaque correlation IDs
- Bounded status, code, component, and operation labels
- Integer durations, exit codes, attempts, and HTTP status
- Recoverable and expected flags
- Prompts, responses, or message content
- Files, file contents, or tool input/output
- API keys, tokens, passwords, or credentials
- Names, emails, or personal identifiers
- Raw command lines, environment values, or logs
- Screen, microphone, camera, contacts, or browser data
- Arbitrary JSON fields
Telemetry contract
One sanitized event is one bounded fact. Consumers should validate the schema string before reading any other field.
{
"schema": "sidewisp.telemetry.v1",
"eventId": "evt_01JZQY7Q9Y6V8H4D4T6P3A",
"installationId": "sw_ins_example123",
"sequence": 42,
"occurredAt": "2026-07-24T08:20:00.000Z",
"observedAt": "2026-07-24T08:20:00.012Z",
"runtime": {
"kind": "openclaw",
"name": "gateway",
"version": "2026.7.1",
"instanceId": "host_a1"
},
"source": {
"kind": "hook",
"adapterVersion": "0.2.0"
},
"type": "tool.failed",
"outcome": "failure",
"correlation": {
"sessionId": "session_7",
"turnId": "run_12",
"toolCallId": "call_3"
},
"details": {
"operation": "github",
"code": "AUTH_FAILED",
"durationMs": 831,
"recoverable": false
}
}eventIdStable event identity. Use as deduplication key.installationIdScoped collector installation identity.sequenceNon-negative local ordering value.occurredAt / observedAtISO timestamps for source occurrence and collection.runtime / sourceAllowlisted adapter and origin metadata.type / outcomeClosed event type plus info, success, failure, or degraded.correlationOpaque session, turn, tool call, message, and parent event IDs.detailsOnly allowlisted safe labels, integers, and booleans.Event catalog
Runtime
runtime.startedruntime.stoppedruntime.restartedruntime.crashedGateway
gateway.connectedgateway.disconnectedTurns
turn.startedturn.completedturn.failedturn.timeoutturn.cancelledTools
tool.startedtool.completedtool.failedtool.timeouttool.cancelledDelivery
message.receivedmessage.deliveredmessage.rejectedmessage.failedProviders
provider.auth_failedprovider.rate_limitedprovider.unavailableRuntime health
queue.stuckqueue.recoveredcontext.exhaustedconfig.invalidplugin.failedCollector
health.snapshotcollector.startedcollector.stoppedcollector.degradedAllowlisted detail fields
codereasonstatuscomponentoperationcapabilityattemptcountdurationMsexitCodehttpStatusrecoverableexpectedCollector defaults
Maximum local spool footprint. Owner-only directory and database permissions.
Maximum events per upload batch, capped at 256 KiB before compression.
Minimum raw batch size before transport switches to gzip compression.
Upload tick and health heartbeat intervals in OpenClaw v0.2.0.
Receiver protocol
A custom endpoint must implement enrollment, HMAC verification, replay protection, batch validation, explicit acknowledgements, and idempotent storage.
POST /v1/installations/exchangeAccept one-time setupToken. Return installationId and installationSecret. Consume token once.
POST /v1/telemetry/batchesVerify installation, timestamp, nonce, and HMAC against raw body before decompression or JSON parsing.
Accept only known schemas and allowlisted fields. Make repeated eventId delivery harmless.
Return accepted IDs and permanent per-event rejections. Unacknowledged events remain in local spool for retry.
Point OpenClaw to your receiver
openclaw config set plugins.entries.sidewisp.config.endpoint https://telemetry.example.com
openclaw config set plugins.entries.sidewisp.config.setupToken sw_setup_REPLACE_ME
openclaw gateway restartPoint command-hook runtimes to your receiver
# Codex
SIDEWISP_ENDPOINT=https://telemetry.example.com \
./scripts/install-codex.sh sw_setup_REPLACE_ME
# Claude Code
SIDEWISP_ENDPOINT=https://telemetry.example.com \
./scripts/install-claude-code.sh sw_setup_REPLACE_MEA URL change alone is not enough. Receiver must implement the exchange and signed batch contracts below over HTTPS.
Enrollment
POST /v1/installations/exchange
Content-Type: application/json
{ "setupToken": "sw_setup_REPLACE_ME" }
200 OK
{
"installationId": "sw_ins_example123",
"installationSecret": "sw_secret_REPLACE_ME_WITH_RANDOM_SECRET"
}Batch and signature
{
"schema": "sidewisp.telemetry-batch.v1",
"events": [
{ "...": "sidewisp.telemetry.v1 event" }
]
}digest = SHA256(rawRequestBody)
canonical = timestamp + "\n" + nonce + "\n" + hex(digest)
signature = HMAC_SHA256(installationSecret, canonical)
Authorization: Sidewisp <installationId>:<hex(signature)>
X-Sidewisp-Algorithm: hmac-sha256-v1
X-Sidewisp-Timestamp: <unix-seconds>
X-Sidewisp-Nonce: <random-base64url>The raw request body may be gzip-compressed and carriesContent-Encoding: gzip. Verify HMAC over those exact received bytes. Enforce a short timestamp window, reject nonce reuse, compare signatures in constant time, cap body size, and parse JSON only after authentication succeeds.
Partial acknowledgement
{
"acknowledgedEventIds": [
"evt_01JZQY7Q9Y6V8H4D4T6P3A"
],
"rejected": [
{
"eventId": "evt_invalid",
"code": "invalid-schema"
}
]
}Process valid events. Return accepted IDs and permanent event rejections.
Credential invalid or revoked. Collector reports credential-rejected.
Temporary rate limit. Optional Retry-After controls bounded backoff.
Temporary receiver failure. Collector retains events and retries with jitter.
Build your own stack
The plugin does not generate a dashboard. It exposes enough stable, privacy-safe structure for a developer or coding agent to build one.
Local health dashboard
Run a receiver on your own machine, keep SQLite local, and show uptime, recent failures, tool outcomes, and spool health for one agent.
Node.js · SQLite · ReactFleet operations
Group events by installation and runtime instance. Build status boards, failure timelines, duration percentiles, and crash-loop detection across many agents.
Postgres · ClickHouse · ReactAlerts and routing
Route bounded failure facts to Slack, Telegram, Discord, PagerDuty, email, or a generic webhook without forwarding prompts or tool payloads.
Webhooks · Queues · RulesMetrics and Grafana
Translate event counters, durations, provider failures, and health snapshots into Prometheus metrics and operate with your existing Grafana stack.
Prometheus · GrafanaInternal admin tools
Embed agent health into an existing operations console. Join installation IDs to your own inventory without changing the plugin contract.
Your API · Your UI · SSONew runtime adapter
Map lifecycle facts from another runtime into the same closed schema. Keep content out, preserve stable correlation IDs, and reuse the delivery layer.
Custom runtime · Public contractTurn this contract into a working product.
Give the prompt to Codex, OpenClaw, Claude Code, or another capable coding agent. Add your preferred framework, storage, deployment, authentication, and alert destinations.
Read https://sidewisp.com/docs/ and the Sidewisp plugin source.
Build a TypeScript receiver that:
- implements POST /v1/installations/exchange;
- verifies Sidewisp HMAC signatures before parsing telemetry;
- stores deduplicated sidewisp.telemetry.v1 events in SQLite;
- acknowledges accepted event IDs and rejects invalid events explicitly;
- exposes a read-only JSON API;
- serves a React dashboard with runtime health, event timeline, failure
categories, tool durations, crash loops, and provider errors;
- sends failure alerts to my chosen webhook;
- never stores prompts, responses, files, credentials, identities,
message content, or tool input/output.
Add tests for signature verification, replay rejection, duplicate delivery,
partial acknowledgement, schema validation, and privacy exclusions.Upgrade, roll back, remove
Credentials and pending telemetry live outside the package. Preserve runtime state across upgrades and verified rollbacks.
Inspect and support
openclaw gateway call sidewisp.status --json
openclaw gateway call sidewisp.supportBundle --jsonThe support bundle excludes setup tokens, installation secrets, event payloads, prompts, responses, identities, and full endpoint paths.
Upgrade or roll back
# Install verified target
openclaw plugins install git:github.com/golem-workers/[email protected] --force
openclaw gateway restart
openclaw gateway call sidewisp.status --json
# Roll back package without deleting state
openclaw plugins install git:github.com/golem-workers/[email protected] --force
openclaw gateway restartDisable or uninstall
# Disable collection, retain package and state
openclaw config set plugins.entries.sidewisp.config.enabled false
openclaw gateway restart
# Preview, then remove package
openclaw plugins uninstall sidewisp --dry-run
openclaw plugins uninstall sidewisp
openclaw gateway restartUpdate or remove command-hook adapters
# Update: run installer from the verified target release
./scripts/install-codex.sh
./scripts/install-claude-code.sh
# Remove only Sidewisp hook handlers
./scripts/uninstall-codex.sh
./scripts/uninstall-claude-code.shReinstall uses the existing scoped credential, so a new setup token is required only after revocation or state removal. Uninstall preserves credentials, pending telemetry, releases, and unrelated runtime hooks.
awaiting setupNo active credential. Create a fresh single-use setup token, configure it, and restart.
enrollment-failedCheck outbound HTTPS, endpoint origin, token freshness, and system time.
credential-rejectedInstallation may be revoked. Issue replacement enrollment from an authorized receiver.
spool degradedCheck disk capacity and ownership. Never edit SQLite while collector is running.
plugin not loadedInspect plugin runtime and compare Node.js/OpenClaw versions with release compatibility.
delivery retryCheck DNS, TLS, clock, receiver availability, rate limits, and response contract.
Security and license
The collector remains metadata-only, outbound-only, zero-LLM, and unable to control the observed agent.
Least privilege
User-owned state, outbound HTTPS, detected runtime paths only. No screen, microphone, camera, browser data, or broad filesystem access.
Scoped and local
Setup token is short-lived. Installation secret is stored owner-only and used only to sign telemetry delivery.
Read-only surface
OpenClaw exposes operator-read methods. Codex and Claude Code hooks emit no decisions or model-visible output. Plugin adds no agent tools or providers.
Private disclosure
Report vulnerabilities through GitHub private security advisories. Never attach tokens, event databases, or runtime content.
GNU AGPLv3 only
Plugin releases beginning with v0.2.0 useAGPL-3.0-only. Personal and commercial use, modification, and redistribution are allowed. Covered modified versions and derivative works must remain under AGPLv3, with corresponding source provided when the license requires it.
Sidewisp's hosted storage, analysis, incidents, notifications, and recovery workflows are separate managed services and are not licensed by the plugin repository.