Develop With Oso Cloud
Set Up Your Environment

Development Environment

Oso provides a set of developer tools to streamline the development process.

Install the VS Code extension

If you use VS Code, you can install the Oso Extension from the IDE support section. You can also install it through the Extensions panel of VSCode. This will install the Oso Cloud CLI as well. The extension features include:

  • Polar syntax highlighting
  • Errors and warnings from Oso policies
  • Run policy tests from the code pane

If you are done with the VS Code extension installation, you can skip to the 'Install the Oso Cloud CLI' section.

Implement LSP in other editors

The Language Server Protocol is a specification that lets people write rich developer tooling in an editor-agnostic way. We built our own LSP implementation for Polar policy files, which includes standard features like syntax validation as well as Polar-specific features such as shorthand expansion and unit test integration.

How to get the LSP working for you depends on your environment, and we are actively working on making it easier to use for the rest of the editors.

Console text editors (Vim, Emacs, etc.)

If you use a console text editor like Vim or Emacs, you can run the LSP through the oso-cloud binary, using:

oso-cloud lsp

On the web

Oso Cloud’s policy editor in code mode leverages the Polar LSP by default. It’ll be available as soon as you log in.

JetBrains

To get it working in WebStorm or IntelliJ, follow the steps below:

Install Polar syntax highlighting:

Install Oso LSP:

  • Install the LSP4IJ plugin (opens in a new tab)
  • Go to Language & Frameworks > Language Servers
  • Create a new one with: Server > Command: oso-cloud lsp, Mappings > File name patterns: *.polar , language ID: polar

Install the Oso Cloud CLI

If you didn't install the VS Code extension, you can install the Oso Cloud CLI manually by following the instructions for your operating system.

The Oso Cloud CLI provides console integration for Oso Cloud. Once it's installed, you can:

  • Validate Polar syntax oso-cloud validate
  • Run policy tests oso-cloud test
  • Deploy policies to Oso Cloud or the Oso Dev Server oso-cloud policy
  • Generate typescript types from your policy oso-cloud generate-types

On Windows, the command is oso_cli (e.g. oso_cli validate)

The CLI provides many other instructions. See the CLI page for complete documentation.

Install the Oso Dev Server

The Oso Dev Server is a local instance of Oso Cloud that you can use to test authorization-dependent application logic without the need for communicating with the remote Oso Cloud service.

Install the latest version of the Oso Dev Server from the install page (opens in a new tab) in the Oso Cloud UI.

We currently provide the Oso Dev Server for Mac OS and Linux. On Windows, you can run the Oso Dev Server in a Docker image by using the Dockerfile provided on the install page (opens in a new tab).

Configure your local environment to use the Oso Dev Server

Once you've installed the Oso Dev Server, configure your system to use it:

CLI

  • Set the OSO_URL environment variable to http://localhost:8080
  • Set the OSO_AUTH environment variable to e_0123456789_12345_osotesttoken01xiIn

Client SDK

Consult the API documentation to find the instructions for initializing the client with the local URL and API token.

For example, you would instantiate the Node.js client as follows:


const { Oso } = require("oso-cloud");
const oso = new Oso(
"http://localhost:8080",
"e_0123456789_12345_osotesttoken01xiIn"
);

See Use the Oso Dev Server for comprehensive documentation about the Oso Dev Server.

Next steps

Now that you've installed the developer tools, you can use them to build a powerful local development workflow. Read the workflow walkthrough to learn how.

Local Development Workflow