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

# Build and run the whole stack in Docker
$ make docker_dev

Requires Docker and Docker Compose. The stack is defined in docker-compose-dev.yml.

Frontend (React SPA)

https://localhost:8444
The primary operator experience.

Legacy admin UI

https://localhost:8443
The server-rendered osctrl-admin interface.

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.26.3+ (and Node.js 20+ if you're working on the frontend).

$ git clone https://github.com/jmpsec/osctrl.git
$ cd osctrl
$ make

Compiles all components — osctrl-tls, osctrl-admin, osctrl-api, osctrl-cli — into bin/, and builds the frontend bundle. For frontend-only work: make frontend-dev.

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, and carve files when you need artifacts.

Full guides at osctrl.net — deployment, components, CLI usage and API reference.

Deploy osctrl your way