Self-hosted service
permitio/opal avatar
permitio/opal

OPAL, a policy update layer whose quickstart pipes a compose file off master

Policy and data administration, distribution, and real-time updates on top of Policy Agents (OPA, Cedar, ...)

5,519 stars309 forksPythonApache-2.0

At a glance

What is it?
OPAL watches policy and data sources and pings OPA and Cedar agents so their decisions reflect what just changed. The architecture is stateless by design, with the client fetching the payload itself, and the one command the page advertises downloads a compose file from a moving branch and runs it.
Who is it for?
OPAL fits a team already running OPA or Cedar and already owning the data behind its authorization decisions, because the value is in propagation rather than in evaluating policy. Before you adopt it, read the trust boundary properly.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • permitio/opal5,519 ★ · +6
Star history
Repository2026-09-232026-11-15
permitio/opal5.5k5.5k

6 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The one command quickstart pipes a compose file off master

The TL;DR section is a single command:

code
curl -L https://raw.githubusercontent.com/permitio/opal/master/docker/docker-compose-example.yml \
> docker-compose.yml && docker compose up

Four things happen in one line. A compose file is fetched over HTTPS from the `master` branch rather than from a tag or a release, so the contents change whenever anyone merges to that branch. It is written into the current directory as `docker-compose.yml`, overwriting whatever was there. `docker compose up` then builds and starts whatever that file declares, which for a compose file can mean pulling images and bind mounting host paths. And there is no checksum, no pinned commit, and no review step between the fetch and the run. This one is worth reading twice before it is pasted.

The server publishes a topic, and the client fetches the payload

The architecture paragraph is short and load bearing. OPAL is described as a stateless client-server architecture in which servers publish policy and data updates over a lightweight websocket PubSub channel, and clients subscribe to it via topics. The next clause is the important one: upon an update, each client fetches data directly from the source to load it into its managed Policy Engine instance. So the server does not carry the payload. It announces that something changed, and every agent goes and reads the origin itself, whether that origin is an API, a database, git, S3, or a third party SaaS. Statelessness on the server side is bought with a requirement on the client side, since each agent needs its own credentials to the source and each one reads it independently.

Makefile defaults point at plain HTTP and a keypair under root

The build file ships four environment defaults:

make
OPAL_SERVER_URL ?= http://host.docker.internal:7002
OPAL_AUTH_PRIVATE_KEY ?= /root/ssh/opal_rsa
OPAL_AUTH_PUBLIC_KEY ?= /root/ssh/opal_rsa.pub
OPAL_POLICY_STORE_URL ?= http://host.docker.internal:8181

Both URLs are plain HTTP, one for the server on port 7002 and one for a policy store on 8181, both addressed at `host.docker.internal` so they resolve from inside a container to the host. The key paths are absolute and sit under `/root/ssh`. Because they are `?=` assignments, any of the four can be overridden on the command line.

Three packages on PyPI, and a script that rewrites the version

The Python side is three distributions in one tree: `packages/opal-common`, `packages/opal-client`, and `packages/opal-server`; the top of the page carries PyPI badges for the server and the client and a downloads counter for the server. The release naming needs a helper, and the repository carries one: `semver2pypi.py` at the root. Release candidates follow each other within days, 0.9.10-rc.3 on 2026-10-23, then 0.10.0-rc.2 on 2026-10-27 and 0.10.0-rc.3 on 2026-10-28, so the newest thing published is a release candidate. The Makefile builds all three with `python setup.py sdist bdist_wheel` and uploads each with `python -m twine upload dist/*`, and `requirements.txt` pins `setuptools>=78.1.1`, a modern setuptools being asked to drive a direct `setup.py` invocation.

Two requirement pins exist because a scanner asked for them

The dependency file is short and its comments are the interesting part:

code
-e ./packages/opal-common
-e ./packages/opal-client
-e ./packages/opal-server
ipython>=8.10.0
pytest
pytest-asyncio
pytest-rerunfailures
wheel>=0.38.0
twine
setuptools>=78.1.1 # not directly required, pinned by Snyk to avoid a vulnerability
zipp>=3.19.1 # not directly required, pinned by Snyk to avoid a vulnerability

The three project packages are installed in editable mode, so a developer clone is a three package workspace rather than three installs. Two of the pins say in the file itself that they are not directly required and exist because a scanner flagged them, which is a rare piece of honesty in a requirements file and also a hint at how the rest of the dependency surface is maintained. `ipython` sits in the same list with no explanation at all. Test tooling is `pytest` with `pytest-asyncio` and `pytest-rerunfailures`, and `pytest.ini` sits at the root next to an `app-tests/` directory.

The Cedar agent is a submodule, not a directory here

The page explains Cedar support by linking to `permitio/cedar-agent`, and the repository root has both `cedar-agent` and a `.gitmodules` file, so the Cedar agent arrives as a submodule reference rather than as vendored source. That distinction matters for anyone building from a clone: a plain clone without submodule initialisation leaves the Cedar path empty. The same is true of the Helm chart, which lives in a separate repository, `permitio/opal-helm-chart`. So three of the deployment paths on the page, the Helm chart, the Cedar agent, and the documentation site under `documentation/` with its `netlify.toml`, all live partly outside this tree.

The production figures are self-reported and the customer names are not links

The page states that OPAL is the core engine of the Permit.io authorization service and serves in production, then lists three numbers: more than 10,000 policy engine deployments, more than 100,000 policy changes and data synchronizations every day, and more than 10,000,000 authorization checks every day. Nothing on the page attributes them, dates them, or explains what a policy engine deployment counts as, and the three figures sit above a second claim, that OPAL is used in production by Tesla, Walmart, The NBA, Intel, Cisco, Live-Oak Bank, and thousands of other teams. Those six names are set in bold text with no hyperlink attached, while every other destination on the page, including the Slack invite and the Twitter follow button, is a link. The claims are plausible and unfalsifiable from the page, which is worth knowing before you treat the numbers as a benchmark.

Editorial conclusion

OPAL fits a team already running OPA or Cedar and already owning the data behind its authorization decisions, because the value is in propagation rather than in evaluating policy. Before you adopt it, read the trust boundary properly. The server sends a topic notification and the client fetches the payload from the original source, so every agent needs read access to that source rather than trusting the server's copy. Pin the compose file you run instead of curling it off a branch. And check the Makefile defaults before using them, since they point at plain HTTP endpoints and a keypair under a root owned path.

Frequently asked questions

What does OPAL do for OPA and Cedar?

It is an administration layer that detects changes to both policy and policy data and pushes live updates to the agents. It supports Open Policy Agent and AWS' Cedar Agent, and it is described as a stateless client-server architecture where servers publish updates over a websocket PubSub channel that clients subscribe to via topics.

How do I run OPAL for the first time?

The page offers Python packages with a built-in CLI as well as pre-built Docker images, plus a docker-compose playground, a containers getting started guide, and a Helm chart in a separate repository. Its TL;DR is a single command that curls `docker/docker-compose-example.yml` from the `master` branch into `docker-compose.yml` and then runs `docker compose up`.

Where does an OPAL client get the updated policy data?

From the original source, not from the server. Upon an update the client fetches data directly, whether that is an API, a database, git, S3, or a third party SaaS, and loads it into its managed policy engine instance. That is what lets the server stay stateless.

Which Python packages does the OPAL repository publish?

Three: `opal-common`, `opal-client`, and `opal-server`, each built with `python setup.py sdist bdist_wheel` and uploaded with twine. The repository carries `semver2pypi.py` for translating release tags into PyPI versions, and the newest release is 0.10.0-rc.3 from 2026-10-28.

How can I extend OPAL to read from my own data source?

With FetchProviders. The page links a how-to on writing your own fetch provider, alongside tutorials on triggering data updates through OPAL, the basic configuration concepts, and running Cedar with OPAL in a multi-language project. The Cedar agent itself is a separate repository referenced as a submodule from this one.

Official sources

  1. License: Apache-2.0
  2. permitio/opal on GitHub
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/permitio-opal.svg)](https://hysenlabs.com/projects/permitio-opal)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/permitio-opal.svg)](https://hysenlabs.com/projects/permitio-opal)

Was this useful?