Use the Local Oso Cloud Binary
Whether iterating on your policy locally or running integration tests in CI, hitting a remote service is not always the ideal developer experience. To bridge that gap, we offer a stripped-down Oso Cloud binary that you can run offline.
Installation
The binary is available for download from the Install page (opens in a new tab) in the Oso Cloud UI.
Versioning
The install links for the binary contain a semver version number, e.g.
{root-url}/{version}/{tarball}.
When using the binary in a CI/CD pipeline, we recommend pinning to a specific version.
You can check the version of the binary by running standalone --version.
Note: we consider the on-disk file format to be part of the API for
semver versioning. When upgrading between major versions, you will
need to delete and recreate any files stored in the OSO_DIRECTORY.
Setup
Once the binary is installed, you run it the same way you would run a dependency like Postgres or Redis locally. You need to make sure that the Oso Cloud CLI and the Oso Cloud client library integrated into your application are both configured to point at the local binary using the local development test credential.
For the CLI, set the OSO_URL environment variable to http://localhost:8080
and the OSO_AUTH environment variable to
e_0123456789_12345_osotesttoken01xiIn. If you use that API key against the
Oso Cloud production service or use one of your real API keys against the local
service, you will encounter authentication failures.
For the various language integrations, consult the API documentation for how to pass the local URL and API token to the constructor. E.g., for the Node.js library, you would instantiate it like so:
const { Oso } = require("oso-cloud");const oso = new Oso( "http://localhost:8080", "e_0123456789_12345_osotesttoken01xiIn");
By default, the binary will run on port 8080 and store local data in a .oso/
directory. You can override either by setting the OSO_PORT and
OSO_DIRECTORY environment variables, respectively.
We recommend creating a script that starts up the service by invoking the
binary, loads your policy and a set of seed facts via either the oso-cloud
CLI or one of the language clients, and then
gracefully resets the binary's data on exit via the CLI's clear command.
Initializing the policy
The local binary supports passing in a list of policy files to initialize the environment with.
e.g. run ./standalone main.polar tests.polar to start the binary and load the two policy files.
The local binary also supports a --watch-for-changes which will reload the policy files whenever
any file changes. This can be useful for local development.
Caveats
- The binary is not for production use. It does, however, support all APIs, and there is no hard limit on the number of facts it supports.
- The binary is a stateful service that currently only supports a single environment with a single active policy and set of facts. Integration tests that depend on the local binary being in a particular state should not be run in parallel.
- While we try to release new versions of the binary as we update the running Oso Cloud service, there may be a lag. Additionally, the binary does not currently have a 'check for updates' mechanism built-in, so updating to the latest version will fall on users. For both of these reasons, you should not rely on the validation and evaluation semantics of the local binary exactly matching the Oso Cloud service, and, critically, you should do all final, pre-production validation of policy, data (facts), and enforcement changes against the live Oso Cloud service.
Feedback
We are actively iterating on developer experience and would appreciate all feedback on the local development binary and the broader development experience with Oso Cloud. Please do not hesitate to reach out on Slack (opens in a new tab) and/or submit ideas via the feature request portal (opens in a new tab) in the Oso Cloud UI.