Getting Started

Option 1 · Recommended

🐳 Docker Compose

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.

What comes up

nginx, the React frontend, osctrl-api, osctrl-tls, a CLI bootstrap, PostgreSQL, Redis and sample osquery clients.

Where to go

https://localhost:8444
The operator frontend. Tear it all down again with make docker_dev_down.

Option 2

🤖 Provisioning script

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.

Option 3

🏗 Build from source

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.

Optional · New

🛠️ Turn on vulnerability monitoring

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.

Optional · New

🎅 Sync Santa on your Macs

Off by default. Enable it on both services, then point Santa at the environment your Macs are already enrolled in.

# osctrl-tls serves the Santa sync protocol
$ osctrl-tls --santa-enabled

# osctrl-api manages rules, the token, machines and events
$ osctrl-api --santa-enabled

In the operator UI, open the environment's Santa page, set the mode to MONITOR, rotate the token and copy the SyncBaseURL. Deploy both, under SyncBaseURL and SyncExtraHeaders, in the com.northpolesec.santa configuration profile through your MDM. Santa only syncs as a Mac already enrolled in osquery in that environment.

Installing Santa and pre-approving its system extension is covered in Santa's deployment guide and configuration reference. The full osctrl rollout is in pkg/santa.

Optional

🤖 Connect an AI agent over MCP

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.

Next steps

From zero to managed fleet

Create an environment

Environments group your nodes and hold their osquery configuration, enrollment secrets and query schedules.

Enroll your nodes

osctrl generates enrollment packages and one-liners per environment. Point your osquery agents at your TLS endpoint and they appear in the UI.

Query your fleet

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.

Deploy osctrl your way