> ## Documentation Index
> Fetch the complete documentation index at: https://www.osohq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Deploy and configure the self-hosted stack on your host.

## 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:

```bash theme={null}
tar xzf agent-self-hosted-*.tar.gz
cd agent-self-hosted
```

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

## Load the images

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

```bash theme={null}
./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.

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

### Databases

Set `CONTROL_DATABASE_URL` and `AGENT_EVENTS_DATABASE_URL` to the databases from [Requirements → PostgreSQL](/docs/oso-for-agents/self-hosting/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](/docs/oso-for-agents/self-hosting/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](/docs/oso-for-agents/self-hosting/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:

```bash theme={null}
docker compose up -d
```

<Warning>
  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.
</Warning>

## First login

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:

```bash theme={null}
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.