Hybrid Deployment

Oso Cloud runs nodes at the edge across multiple regions and availability zones to ensure high availability (up to 99.99% uptime). Oso Cloud is designed to withstand multiple zone and regional outages without any customer-visible impact. We make this level of investment in availability and resilience to save you from having to do so – developing a high availability strategy, running your own infrastructure, building your own alerting, and so on.

Still, for some use cases, you may prefer to add an additional layer of assurance on top of this. For this, we provide the Oso Fallback node. The objective of the Fallback node is to provide the benefits of a fully-managed cloud service with the comfort of owning your infrastructure.

The Oso Fallback node is a read-only instance of Oso that you run in your VPC. If Oso Cloud ever becomes unavailable, the Oso Client will make authorization checks against the Fallback node. The Fallback node works by pulling down the latest copy of your environment's rules and data from Oso Cloud. It may lag ongoing changes to rules and data by up to 30 minutes. The Fallback node is intended only as a last-resort measure to ensure you can make authorization checks even if Oso Cloud is unavailable and will not work as a replacement for making authorization calls to Oso Cloud as part of normal operations.

The Oso Fallback only supports Check API endpoints used for determining access and does not currently support the Management API endpoints used for retrieving the raw rules and data.

This feature is only available for paid organizations.

Oso Fallback is currently in beta. Reach out if you're interested in learning more:


Each Oso Fallback node runs as a standalone process, and we recommend you deploy it as a sidecar to your existing applications. However, we distribute the software as a Docker image to support multiple deployment models if a sidecar is not suitable for your architecture.

System Requirements

The minimum requirements for running the Oso Fallback node are:

  • 1 CPU;
  • 256MB RAM; and
  • 3x the disk space required for your environment.


You must configure the following environment variables to start the Oso Fallback node:

Environment VariableDescription

Additional environment variables you may configure include:

Environment VariableDefaultAccepted ValuesDescription
OSO_CLIENT_IDRandomly generated UUIDString containing the following characters: a-zA-Z0-9.-Unique identifier for each Oso Fallback node.
If set, the OSO_CLIENT_ID must be unique per restart or redeployment.
OSO_DISABLE_ERROR_LOGGINGfalsetrue, falseWhether error logs are sent to Oso's error collector for review and analysis.
OSO_DISABLE_TELEMETRYfalsetrue, falseWhether usage data are sent to Oso's telemetry collector for review and analysis.
OSO_LOG_LEVELerrorinfo, warn, errorVerbosity of log messages printed to stdout.
OSO_PORT80800 to 65535Port for the Oso Fallback node to listen on.


A healthy Oso Fallback node responds with HTTP OK (200) on /api/healthcheck. You may probe this endpoint to assess the liveness of the node in production environments.

Additionally, you may view the statuses of the connected Fallback nodes on the Fallback status page (opens in a new tab).

Updating Oso Clients

The provided clients support an additional parameter for the Fallback node host. On every request, the client tries Oso Cloud first. If Oso Cloud returns repeated HTTP 5xx or HTTP connection errors, the Oso Client will automatically make the same request against the provided Fallback host.

The following sample code illustrates initializing the Oso Client with an Oso Fallback node running as a sidecar exposed on port 8080:

const apiKey = "<please provide your api key here>";
const oso = new Oso("https://api.osohq.com", apiKey, { fallbackUrl: "http://localhost:8080" });


We actively invest in ensuring high availability and would appreciate all feedback on Oso Fallback and additional features you would like to see. 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.