Core0 / Nio
Core0
GitHub v2.4.4
Overview · Getting Started

# Execution assurance for your AI agent.

Nio scans third-party code for risks, evaluates every runtime tool call against a seven-phase guard pipeline, and keeps an audit log of what happened and why. Install it once per agent and forget it.

## What Nio does

Nio plugs into your agent's hook system and listens to its lifecycle events — when a tool is about to run, when one finishes, when a task starts or stops, when a session ends. Every observed event is recorded as OpenTelemetry metrics, traces, and audit logs. Events that propose an action (a command, a file write, a network request) also pass through the seven-phase guard pipeline, which decides whether to allow, confirm, or deny. Skills and third-party plugins are scanned before they run for the first time for shell exec, secret reads, webhook exfil, obfuscation, and similar risks.

Three capabilities

- Code scan — 15 static rules + markdown/base64 decoding for skills, plugins, and any codebase.
- Runtime guard — a seven-phase pipeline (0–6) that scores every tool call and decides.
- Audit log — every decision is persisted to `~/.nio/audit.jsonl` and optionally shipped to an OTLP collector.

## Pick your agent

Nio ships as a plugin for each supported platform. The scan, guard, and audit logic is the same across all platforms; only the wiring differs. One curl-piped-shell command on the Installation page handles every platform.

- Claude Code — hooks into `PreToolUse` / `SessionStart`.
- Codex CLI — 5/6 lifecycle hooks via `~/.codex/config.toml` + the `codex_hooks` feature flag.
- OpenClaw — registered as a bundled plugin with a single `plugin.js`.
- Hermes Agent — seven shell-hook entries in `~/.hermes/config.yaml` + a small Python plugin for `/nio`.

## First commands

Once installed, the `/nio` skill is available in your agent. Start with:

    /nio config show              # display current protection level + config path
    /nio config balanced          # switch between strict | balanced | permissive
    /nio config import nio.yaml   # apply an operator-provided config (doctor-gated; auto-backup)
    /nio scan .                   # scan the current working directory
    /nio action "rm -rf /"        # evaluate a proposed command without running it
    /nio report                   # last 50 guard decisions + diagnostics summary
    /nio doctor                   # validate config + dry-run OAuth/LLM

See the full command reference at /nio commands.

Already have a team config? Skip the per-machine tuning and apply an operator-provided `nio.yaml` at install time with `./setup.sh --config /path/to/nio.yaml` (or via the curl one-liner). Nio runs `/nio doctor` against the file first and aborts the install if any probe fails — see Onboarding with a shared config.

Something doesn't work? Run `/nio doctor` first — it validates the config schema, dry-runs OAuth credentials, and sanity-checks the LLM API key, with actionable hints. See Diagnostics for the full failure-surface model.

## Telemetry · OTLP collector

Optional but useful for observability. Every hook event Nio sees is shaped into OpenTelemetry data and exported through the bundled async collector. Three signals are emitted:

Signal | What's emitted
--- | ---
Metrics | `nio.tool_use.count` · `nio.turn.count` · `nio.decision.count` · `nio.risk.score` (histogram)
Traces | One trace per conversation turn. Spans: `invoke_agent UserPromptSubmit` (turn root), `execute_tool <name>` (PreToolUse → PostToolUse), `task:execute` (subagent dispatch). Span names follow the OTel GenAI semantic conventions.
Logs | Audit entries — guard decisions, skill scans, lifecycle events, hook events. Read via `/nio report`.

### Where the data goes

- Audit log is dual-written — every guard decision and lifecycle event ships to OTLP and a local JSONL at `~/.nio/audit.jsonl` (rotates at 100 MB). Even with no remote collector you keep a full local trail.
- Metrics and traces are OTLP-only — no local file. If `collector.endpoint` is empty they drop on the floor.
- Remote OTLP — set `collector.endpoint` and Nio POSTs to `/v1/metrics`, `/v1/traces`, `/v1/logs` on that base URL. Bearer auth via `collector.api_key`.
- Protocol — `http` on port 4318 (default) or `grpc` on port 4317.
- Per-signal switches — metrics / traces / logs can be turned on or off independently. Empty endpoint + `logs.local: false` turns the collector into a no-op.

Full schema (every metric, every span attribute, every audit field): Collector Signals. Config field reference: `collector.*` config.

### What you can do with it

- Pipe into Grafana / Honeycomb / Datadog / Tempo to watch live agent activity.
- Aggregate `nio.risk.score` histograms across a fleet to spot drifting protection levels.
- Replay `~/.nio/audit.jsonl` for incident review without needing the collector running.

## Next

- Understand the pipeline: Pipeline overview → start with Phase 0 — Tool Gate.
- Tune behavior: Config reference covers every field in `~/.nio/config.yaml`.
- How scores decide: Scoring.