How-To Guides
Debug & Test
Local Development

Local Development

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.

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.

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.

Local Environment