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

🤖 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