Three paths to a running deployment: Docker Compose for a quick start, the provisioning script for native installs, or building from source — then switch on vulnerability monitoring and MCP if you want them.
The fastest way to get a fully functional deployment — all services, PostgreSQL and Redis wired together.
# Clone the repository $ git clone https://github.com/jmpsec/osctrl.git $ cd osctrl # Prepare the environment file and development certificate $ cp .env.example .env $ make docker_dev_certs # Build and start the whole stack $ make docker_dev_build $ make docker_dev_up
Requires Docker and
Docker Compose.
The stack is defined in docker-compose-dev.yml.
nginx, the React frontend, osctrl-api, osctrl-tls, a CLI bootstrap, PostgreSQL, Redis and sample osquery clients.
https://localhost:8444
The operator frontend. Tear it all down again with make docker_dev_down.
The deploy/provision.sh script installs all dependencies and configures
osctrl on a recent Ubuntu LTS system — usable for development and, with care, for production deployments.
# From a fresh Ubuntu LTS machine $ git clone https://github.com/jmpsec/osctrl.git $ cd osctrl $ ./deploy/provision.sh --help
See the native deployment documentation for full usage, flags and production guidance.
All you need is Go 1.27.1 (and Node.js 22+ if you're working on the frontend).
$ git clone https://github.com/jmpsec/osctrl.git $ cd osctrl $ make
Compiles all components — osctrl-tls, osctrl-api,
osctrl-cli, osctrl-mcp — into bin/,
and builds the frontend bundle. For frontend-only work: make frontend-dev.
For the MCP server alone: make mcp.
Prefer packages? Tagged releases ship DEB and RPM packages for osctrl-tls,
osctrl-api and osctrl-cli with systemd units, plus
standalone osctrl-mcp binaries for Linux, macOS and Windows on amd64 and arm64 —
see the releases page.
Off by default. Enable it on both services, then apply a vulnerability profile to the environments you want covered.
# osctrl-tls stores the software inventory $ osctrl-tls --vuln-enabled # osctrl-api downloads advisories, matches them and serves findings $ osctrl-api --vuln-enabled # Optional: also match Windows, macOS, Homebrew and Chocolatey via NVD $ export VULN_NVD_API_KEY=<your-nvd-key> $ osctrl-api --vuln-enabled --vuln-nvd-enabled
Then apply a vuln-linux, vuln-darwin or
vuln-windows profile to an environment's schedule from the operator UI.
The queries run daily in snapshot mode. Findings appear once the first feed sync completes —
the initial NVD sync is slow by design, since it respects NVD's published rate limit.
Air-gapped? Mirror the OSV bucket layout and the KEV JSON internally, then point
--vuln-osv-url and --vuln-kev-url at them.
Package inventory never leaves your deployment either way.
Point an MCP client at your deployment and it can inspect the fleet — environments, nodes, the osquery schema, query results — bounded by the token you give it.
# Create a dedicated, read-scoped service user first $ osctrl-cli user add -u mcp-agent -s -e prod $ osctrl-cli user permissions -u mcp-agent -e prod --user # Then register the stdio server with your client $ claude mcp add osctrl \ --env OSCTRL_API_URL=https://osctrl.example.com \ --env OSCTRL_API_TOKEN=<service-user-token> \ -- /opt/osctrl/bin/osctrl-mcp
Or skip the binary entirely: set mcp.enabled: true in
api.yml and point clients at
https://<your-host>/api/v1/mcp, where each user authenticates as themselves.
Write tools stay off until you turn them on.
Full tool list and client examples in
MCP.md.
Environments group your nodes and hold their osquery configuration, enrollment secrets and query schedules.
osctrl generates enrollment packages and one-liners per environment. Point your osquery agents at your TLS endpoint and they appear in the UI.
Run on-demand distributed queries, schedule packs, open a node console, set alert rules, and carve files when you need artifacts.
Full guides at docs.osctrl.net — deployment, components, CLI usage and API reference.
Join #osctrl in the osquery Slack, or open an issue on GitHub.