Installation

Obtain the distribution

Download the distribution from the Oso dashboard: open Organization settings → Self-hosted, choose a version, and select Get link to generate a download URL for the tarball. Unpack it and enter the directory:

tar xzf agent-self-hosted-*.tar.gz
cd agent-self-hosted

Self-hosted downloads are enabled per account. Contact Oso to turn on access for your account before you begin.

Load the images

The distribution bundles every image the stack needs, so you load them into Docker:

./load-images.sh

Configuration

All configuration lives in .env, next to docker-compose.yml. Run ./initialize-environment.sh to create it: the script generates the secrets and leaves blanks for you to fill in — the database URLs, public URL, OIDC settings, and admin emails. Every variable is required; the stack won’t start with one missing, and an unfilled blank counts as missing.

Run ./initialize-environment.sh once. Re-running requires --force and rotates every secret.

Databases

Set CONTROL_DATABASE_URL and AGENT_EVENTS_DATABASE_URL to the databases from Requirements → PostgreSQL. Both must already exist — the stack does not create them, so create them now if you haven’t.

Networking

Variable	What
`OSO_PUBLIC_URL`	The address users reach the stack at — the `https://` URL your load balancer terminates TLS at (for example `https://oso.example.com`), or `http://localhost:8080` when running locally. Login redirects derive from it.

The stack publishes two ports on the host: the dashboard on 8080 and the traffic proxy (which agents connect to) on 8090. Every other service — the enforcement engine, the message broker, and the optional evaluator — is reachable only over the Compose network and publishes no host port. The stack does not terminate TLS — put your load balancer or reverse proxy, with your certificate, in front, forward to 8080 (and 8090 if agents connect through it), and set OSO_PUBLIC_URL to that https:// address. The stack must be served over HTTPS except on localhost — see Security → Encryption in transit.

Authentication (OIDC)

Variable	What
`OIDC_ISSUER_URL`	Your IdP’s issuer URL, for example `https://example.okta.com/oauth2/default`.
`OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`	The OAuth client you register for Oso at your IdP.
`ADMIN_EMAILS`	Comma-separated emails granted admin access.

Register <OSO_PUBLIC_URL>/web/oauth/oidc/callback as the redirect URI at your IdP. Everyone who logs in is an operator; ADMIN_EMAILS are the admins, everyone else a member.

Secrets

initialize-environment.sh generates these into .env; leave them as-is. (Operations → Configuration file management covers keeping them stable and backing them up.)

Variable	What
`SECRET_KEY`	Session cookie key; a stable value keeps users logged in across restarts.
`CREDENTIAL_ENCRYPTION_LOCAL_KEY`	Encrypts stored integration credentials at rest.
`OSO_SERVICE_HMAC_KEY`	Authenticates internal service-to-service calls.
`RABBITMQ_PASSWORD`	Message-broker password.
`DEVICE_REGISTRATION_PRE_SHARED_KEY`	Shared token you set here and provide when installing the Oso Agent. Agents must present it to register with this deployment, so the registration endpoint isn’t left unauthenticated.

Optional features

Each of these stays switched off until you configure it:

Feature	How to turn it on
Slack alert delivery	Add your Slack incoming-webhook URL in the dashboard.
EDR device detection (CrowdStrike / SentinelOne)	Add credentials per environment in the dashboard.
LLM alert assessment	Uncomment `EVALUATOR_SERVICE_URL` for `carpincho` in `docker-compose.yml` and give the `evaluator` an `ANTHROPIC_API_KEY` (or an Anthropic-compatible in-network gateway via `ANTHROPIC_BASE_URL`).
Device management registration	Agents authenticate to the registration endpoint with `DEVICE_REGISTRATION_PRE_SHARED_KEY`; distribute it to devices with `oso-setup install --registration-key …`.

Start the stack

Bring it all up:

docker compose up -d

Start from empty volumes. On boot the init containers sync data from your PostgreSQL databases; if the volumes already hold data, the init containers erase it first.

Open your OSO_PUBLIC_URL (for example https://oso.example.com) and log in through your IdP.

Verify the stack

Confirm that the one-time setup containers — ensure_tenant_environment, seed_metadata, init_policy, and oso_sync — each finished with exited (0), then check that the health endpoints answer:

docker compose ps                      # setup containers show exited (0); feature shows healthy
curl localhost:8080/web/healthcheck    # dashboard is up
# the enforcement engine has no host port, so check it from inside the container
docker compose exec feature curl -fsS http://localhost:8081/api/healthcheck

Use docker compose logs <service> to investigate anything that isn’t healthy.

Get Started

Capabilities

Deployment Models

Integrations & Connectors

Self-Hosting

Reference

Obtain the distribution

Load the images

Configuration

Databases

Networking

Authentication (OIDC)

Secrets

Optional features

Start the stack

Verify the stack

​Obtain the distribution

​Load the images

​Configuration

​Databases

​Networking

​Authentication (OIDC)

​Secrets

​Optional features

​Start the stack

​First login

​Verify the stack

Obtain the distribution

Load the images

Configuration

Databases

Networking

Authentication (OIDC)

Secrets

Optional features

Start the stack

First login

Verify the stack