Documentation

Secronyx is a read-only diagnostics server for AI agents. It implements the Model Context Protocol (MCP) over JSON-RPC 2.0, announcing protocol version 2024-11-05, and exposes the state of a host as typed tools with JSON results: CPU, memory, disks, processes, logs, scheduled tasks, kernel and network configuration, installed software and lock files, web and database server configuration, Windows registry and IIS, platform security controls, and triage snapshots that combine them. An AI client never receives a shell. Each tool is a vetted collector that reads the operating system's native interfaces or runs a fixed command with parameterised arguments, and returns a structured document. On a platform where a tool does not apply it returns an empty result rather than an error, so the same tool catalogue can be offered everywhere.

It ships as a single binary for Linux, macOS and Windows. With no configuration it talks to a local client over stdin and stdout, registers every tool except those in the sensitive scope, redacts credentials from output, and writes a hash-chained JSON Lines audit log. An HTTP transport adds remote access with a chain of authenticators (static bearer token, OIDC, OAuth introspection, hashed API keys, SSH-signed requests and mutual TLS), per-client rate limiting, and a start-up check that refuses to listen on a non-loopback address without both authentication and TLS. A hybrid mode connects the same binary outbound to the Secronyx service so fleets behind NAT can be queried without inbound rules. The source is at github.com/levantar-ai/secronyx and the product site is ../index.html.

Where to start

If you have five minutes, read Getting started: it downloads the binary, runs a query without any client, then speaks MCP over stdio by hand so you can see exactly what an agent sees. Installation lists the release assets by name, how to verify their provenance, and the installer, container and service options. Connect an AI client covers Claude Code, Claude Desktop, other stdio clients, SSH, Docker and every HTTP credential type.

Operators deploying beyond one machine should read the Security model before Remote access over HTTP. Everything a flag or environment variable does is in the Configuration reference; every tool and its arguments is in the Tool reference.

Start

• Documentation: this page.
• Getting started: download, run a query, speak MCP over stdio, understand the defaults.
• Installation: release assets and their provenance, per-platform install, installers, Docker, Helm, building from source, running as a service.
• Connect an AI client: Claude Code, Claude Desktop and generic stdio clients; HTTP clients with bearer tokens, API keys, SSH signatures and client certificates.

Reference

• Configuration reference: every command-line flag and environment variable, its default, and what it changes.
• Tool reference: every registered tool grouped by scope, with input schema, platform support and result shape.
• JSON-RPC API: the wire protocol on stdio and HTTP: initialize, tools/list, tools/call, ping, error codes, result caps and the HTTP endpoints.
• Command line: the --query direct mode and the service, apikey and ssh-sign subcommands.

Security

• Security model: threat model, read-only guarantees, defence in depth, and what the server deliberately does not do.
• Authentication: the authenticator chain, bearer tokens, OIDC JWT validation, OAuth introspection, the built-in token server and replay protection.
• Scopes and authorization: the tool scopes, registration-time policy, per-identity grants and the sensitive opt-in.
• Redaction: what is stripped from tool output, the default and GitGuardian providers, and how to switch it off knowingly.
• Audit logging: the JSON Lines event format, the hash chain, rotation, the stderr fallback and --audit-verify.
• Network and path policy: listener exposure rules, CORS, proxy headers, the file-access allowlist and the outbound probe policy.

Deployment

• Remote access over HTTP: TLS, listen addresses, reverse proxies, health and metrics endpoints, and choosing an authentication method.
• Docker and Compose: the image, the Compose services and profiles, host mounts and the privileged variant.
• Kubernetes and Helm: the chart, its authentication and TLS guards, scope values and ServiceMonitor.
• Windows service: the MSI installer, its properties, the Secronyx service and Group Policy or configuration-management rollout.
• Fleet deployment: rolling the agent out to many hosts with installers, packages and configuration management.
• Hybrid and SaaS mode: outbound-only operation against the Secronyx service, registration, wake-up polling and WebSocket sessions.

Tutorials

• Tutorial: diagnose a slow Linux host: from load average to the process, cgroup and journal evidence behind it.
• Tutorial: triage a Windows IIS server: sites, application pools, bindings, request queues and event log correlation.
• Tutorial: check a macOS workstation: launchd jobs, security controls, MDM profiles and application inventory.
• Tutorial: sweep a fleet from one agent: asking the same questions of every host and comparing the answers.
• Tutorial: mutual TLS end to end: a private CA, client certificates, the identity file and revocation.
• Tutorial: per-operator API keys: creating, scoping, expiring, CIDR-pinning and revoking keys.
• Tutorial: SSH key request signing: signing requests with existing SSH keys or certificates and verifying them server-side.
• Tutorial: verify the audit chain: proving an audit file is intact and detecting a tampered or truncated one.

Understanding the product

• Use cases: incident triage, evidence capture, change verification and compliance snapshots.
• Compared with alternatives: an agent with a shell, an LLM driving SSH with a read-only user, and monitoring exporters.
• Compliance mapping: how the controls map to common frameworks and what evidence the audit log provides.
• Architecture: the collector pattern, platform build tags, the command execution seam and the server layers.
• Troubleshooting: start-up refusals, authentication failures, empty results and audit fallbacks, with the exact messages.
• FAQ: short answers to the questions operators ask first.

Project

• Contributing: building, testing, lint and security gates, conventional commits and adding a tool.
• Licensing: the AGPL-3.0 licence, what running and modifying the agent does and does not ask of you, and the contributor agreement.
• Releases and versioning: semantic-release, tags, the SLSA build and what each release contains.
• Reporting a vulnerability: how to report a security issue privately and what to expect.