osctrl puts an operator console in front of your osquery fleet

The remote API, and what the control plane adds

osctrl is a fast and efficient osquery management solution that implements the osquery remote API through a TLS endpoint.

That sentence is the technical core. osquery is the endpoint query engine, and its remote API is how a server asks enrolled machines to run SQL against their own state and send results back. osctrl is the server side of that conversation, with the surrounding operations a fleet of endpoints actually needs.

The list of what you can do with it is the feature set in compact form. You can monitor systems running osquery, distribute osquery configuration, collect status and result logs, run on-demand distributed queries, open a read-only, shell-like node console backed by osquery, browse node files through accelerated, permission-checked requests, carve files and directories, alert on log matches and node state through webhook or email channels, track node posture, GeoIP country metadata and node activity, and check deployment health across the database, Redis, services, workers and upgrade status.

The last item of that list is the one that sets the scale claim: scale from hundreds to hundreds of thousands of nodes.

The documentation also carries a warning that is worth reading before anything else. osctrl is a rapidly evolving project, it is used in production, but it remains under active development, and you should review the documentation and known constraints before deploying it in a critical environment. The licence is MIT, the homepage is osctrl.net, the published documentation is at docs.osctrl.net, and the last push was on 2026-10-18 with v0.6.0 released on 2026-10-11.

Four binaries, one operator UI, and a package tree

The project structure tells you what runs where.

osctrl/
├── cmd/                         # Service and CLI entrypoints
│   ├── api/                     # osctrl-api (REST API service + generated docs)
│   ├── cli/                     # osctrl-cli (operator CLI)
│   ├── mcp/                     # osctrl-mcp (standalone MCP stdio server)
│   └── tls/                     # osctrl-tls (osquery remote API endpoint)
├── frontend/                    # React SPA frontend for the operator UI
├── pkg/                         # Shared application packages

The four binaries are the API service, the operator CLI, the MCP server and the TLS endpoint that speaks the osquery remote API. The frontend is a React single page application for the operator UI, which the highlights describe as modern, with views for nodes, environments, queries, saved queries, carves, tags, users, enrollment, audit log, service configuration, log sinks, auth providers, alerting, node activity, and optional posture data.

Below that sits a pkg directory of shared application packages, and the ones named in the tree show how wide the surface is: activity tracking backed by Redis, an alerts package with rules, channels and a dispatch worker, an audit log manager, shared OIDC and SAML auth state, persisted federated auth provider configs, a database manager with a health canary, cache helpers, carve logic and storage integrations, config structs with flags validation, node console sessions with a commands parser, and a database utility package.

The Makefile confirms the build is a set of separate binaries, with a build target that makes the TLS endpoint, the frontend, the API, the CLI and the MCP server in turn, and a static target for statically linked versions using the external linkmode and extldflags. The Go module is github.com/jmpsec/osctrl and it declares go 1.27.2, with the build commit and build date injected into the binaries at link time.

Per-node configuration and extension delivery, with rollback

Two of the highlights are about changing a running fleet, and both are more careful than they first look.

The first is per-node configuration and flags overrides. Environment admins can layer a JSON override on one node's osquery configuration, or a flags override on its flagfile, from the node page, with optional expiry. Connection settings are protected, every change is audited, and options the environment does not set keep their overridden value on the host until osquery restarts. Flags overrides reach hosts managed by osctrld's service mode on its next sync with an osquery restart, and if osquery rejects them, osctrld rolls back and reports it. Removing or expiring a flags override reverts the host on osctrld's next sync.

The rollback behaviour is the part that makes this usable. An override that osquery refuses does not leave the host in a half-configured state, and the operator is told.

The second is osquery extensions. Super admins upload extension binaries, up to 64 MB per platform, to a database-backed library. Environment admins assign ordinary extensions to an environment, while super admins assign command-execution extensions to single hosts, with optional expiry. osctrld's service mode installs them on its next sync, verifies hashes, rolls back failures, and the node page shows per-extension status.

So there are three roles doing three different things: a super admin who can upload binaries and grant command execution, an environment admin who distributes configuration within their environment, and the host itself, which validates and reports. The 64 MB limit and the hash verification are the practical constraints on the extension pipeline.

The node console, and the file operations behind it

The node console is the feature that distinguishes osctrl from a query scheduler, and it is deliberately restricted.

It is a read-only console for a specific node using hidden accelerated distributed queries. The supported commands are listed in the documentation: pwd, cd, ls, stat, ps, sql, osquery, .tables, and get for permission-checked file carves.

Read-only is the point. A console that could write would be a remote shell on every enrolled machine, and the console is built on the query mechanism rather than on a remote execution agent, so the set of things it can do is bounded by what osquery can answer.

Behind the console sit the file operations. There is a file explorer with accelerated per-node directory listing and stat requests backed by osquery distributed queries, and the accelerated distributed queries themselves are optional, defaulting to a 5 second interval when enabled. Console acceleration is scoped to the target node and to fresh active console sessions, so a stale session does not keep polling a host.

Two more pieces fit here. The osquery schema awareness ships osquery table metadata through version 5.23.1 and exposes authenticated table metadata to the UI and API for query authoring and for the console's .tables command. And the carves feature is the write path, with file carves and directories stored through the storage integrations in the carve package, with authenticated access to the query and carve sample libraries.

Alerting, posture and the health page

Alerting is optional and rule based, and the documentation is specific about its scope and its machinery.

Rules can match on result, status and query logs as well as on node state, with inactive and recovered treated as distinct states. Scoping is global, per environment, or down to a single node. Notifications fan out to webhook and email channels, with Redis-backed cooldown and deduplication, a dispatched history, and hot reload without a restart. Rules can be created straight from a node's page, and a node shows a marker when any rule covers it.

The cooldown and dedupe being Redis-backed matters for a fleet, because the alternative is a notification storm the first time a rule matches something common.

Posture and enrichment are separate and optional. There is posture ingestion, device risk checks mapped to SOC 2 and ISO 27001 objectives, optional MaxMind GeoIP country enrichment, Redis-backed activity tracking, and API-managed service configuration sections.

The health and system status page is behind a flag and disabled by default, and when enabled it fuses a live database ping, a Redis PING, per-service runtime statistics, an osctrl-tls heartbeat, and cached upgrade status. So the deployment can tell you whether it is healthy without you having to check each piece.

The environment file shows the shape of a deployment. It pins the osctrl version at 0.6.0, the osquery version at 5.23.1, an Nginx version, a Postgres version with a database name and credentials, a Redis version, a JWT secret, a session key, an admin user and password, the Go version at 1.27.2, and posture settings including a profile, an interval of 75 and a query prefix.

Security defaults, and the MCP surface

The security-sensitive defaults are listed as one bullet, and they are the ones a reviewer should check first.

JWT authentication is the default for osctrl-api. Optional multi-factor authentication is supported for password logins, with TOTP, passkeys and security keys, and recovery codes. There are trusted proxy controls and audit logging, and access to the query and carve sample libraries is authenticated.

The Model Context Protocol surface is new and worth reading carefully. There is a standalone osctrl-mcp stdio server and an optional hosted endpoint at /api/v1/mcp, and they expose permission-checked fleet inspection tools to MCP clients. Mutating tools are separately gated and disabled by default.

That last sentence is the design you want from an assistant integration. An inspector that can list nodes, check their posture and read their activity is useful and low risk, and a tool that changes a host configuration is a different category of thing, so it gets its own switch and starts off.

The identity side is in the shared packages, with OIDC and SAML auth state in the auth package and persisted federated auth provider configurations in authproviders, which the highlights describe as auth providers in the operator UI. The module dependencies back that up, with go-oidc, crewjam/saml, go-webauthn and golang-jwt all in the go.mod.

Editorial conclusion

Adopt osctrl if you already run osquery and want a control plane rather than a set of enrolled nodes: distributed queries, configuration distribution, log collection, alerting and a per-node console in one place. Do not adopt it into a critical environment without reading its known constraints, since the project states plainly that it is rapidly evolving and still under active development. Before you deploy, check three things: how you will manage the private key that nodes use to enrol, because that is the trust anchor for the whole fleet, whether the environment model and its overrides fit how you segment your hosts, and whether the MCP endpoint is left disabled, since exposing mutating fleet tools to an assistant is a decision rather than a default.

Frequently asked questions

Official sources

1. jmpsec/osctrl on GitHub
2. License: MIT
3. Project website
4. README
5. Releases