Oso Dev Server

Use the Dev Server to evaluate authorization logic locally, without network calls to Oso Cloud.

First time? Install the CLI and editor tools before setting up the Dev Server.

Quickstart

Start the Dev Server using Docker:

docker run -p 8080:8080 public.ecr.aws/osohq/dev-server:latest

Server runs at:http://localhost:8080.

Why use the Dev Server

Faster development cycles with instant policy updates and no network latency.
Offline development when internet connectivity is unreliable or unavailable.
Isolated testing of authorization changes before deploying to production.
CI/CD support for automated testing, no external dependencies.

Installation options

Choose the installation method that fits your development workflow.

Docker (Recommended)

# Basic startup
docker run -p 8080:8080 public.ecr.aws/osohq/dev-server:latest

# With file watching
docker run -p 8080:8080 -v ./policies:/policies public.ecr.aws/osohq/dev-server:latest --watch-for-changes /policies/main.polar

Health check: The Oso Dev Server exposes a healthcheck endpoint that can be used for container orchestration and monitoring (for example, Kubernetes liveness and readiness probes). Endpoint: GET /api/healthcheck Example:

curl http://localhost:8080/api/healthcheck

A successful response indicates that the Dev Server is running and able to serve requests.

Native binary

Download from the Oso Cloud dashboard. macOS/Linux:

# Download and run
./oso-dev-server

# Check version
./oso-dev-server --version

Windows: Download and run the binary from the dashboard.

Environment configuration

Configure your application to use the local Dev Server instead of Oso Cloud. Set these environment variables:

export OSO_URL="http://localhost:8080"
export OSO_AUTH="e_0123456789_12345_osotesttoken01xiIn"

SDK configuration

Configure your application’s Oso client to use the local server.

Node.js
Python
Go

oso.js

const { Oso } = require("oso-cloud");

const oso = new Oso(
  "http://localhost:8080",
  "e_0123456789_12345_osotesttoken01xiIn"
);

oso.py

from oso_cloud import Oso

oso = Oso(
    url="http://localhost:8080",
    api_key="e_0123456789_12345_osotesttoken01xiIn"
)

oso.go

import "github.com/osohq/go-oso-cloud"

client := oso.NewClient(
    oso.WithURL("http://localhost:8080"), 
    oso.WithAPIKey("e_0123456789_12345_osotesttoken01xiIn")
)

Load your policy

Initialize the Dev Server with your authorization policy:

# Start with a policy
./oso-dev-server main.polar

# Auto-reload on changes
./oso-dev-server --watch-for-changes main.polar

Advanced usage

Docker Compose integration

Run alongside your app in local development:

version: "3.8"
services:
  oso:
    container_name: oso_service
    image: public.ecr.aws/osohq/dev-server:latest
    command: --watch-for-changes /main.polar
    ports:
      - 8080:8080
    volumes:
      - ./main.polar:/main.polar
  
  app:
    build: .
    depends_on:
      - oso
    environment:
      - OSO_URL=http://oso_service:8080
      - OSO_AUTH=e_0123456789_12345_osotesttoken01xiIn

Important: Use the service name (oso_service) as hostname when connecting from other containers.

Configuration options

Customize the Dev Server behavior with environment variables:

# Change port (default: 8080)
export OSO_PORT=9000

# Set custom data directory (default: .oso/)
export OSO_DIRECTORY=/tmp/oso-data

# Run with config
./oso-dev-server --port 9000 main.polar

Data Management: The Dev Server stores data in .oso/ directory. Clear it between test runs:

# Reset Dev Server state
rm -rf .oso/

Pin Dev Server versions in CI

# Check current version
./oso-dev-server --version

# Use specific version
docker run public.ecr.aws/osohq/dev-server:v1.2.3

Note: The on-disk file format is part of the API. Clear .oso/ directory when upgrading major versions.

Parallel test environments

Create isolated test environments for parallel integration tests:Create new environment:

# Copy current state
curl -X POST "http://localhost:8080/test_environment?copy=true"
# Returns: { "pub_id": "...", "token": "..." }

# Start empty
curl -X POST "http://localhost:8080/test_environment?copy=false"

Jest integration example:

const { Oso } = require("oso-cloud");

async function createTestOsoClient() {
  const response = await fetch("http://localhost:8080/test_environment", {
    method: "POST"
  });
  const { token } = await response.json();
  return new Oso("http://localhost:8080", token);
}

describe("authorization tests", () => {
  let oso;
  
  beforeEach(async () => {
    oso = await createTestOsoClient();
  });

  test("user can access own resources", async () => {
    const allowed = await oso.authorize("alice", "read", "document:1");
    expect(allowed).toBe(true);
  });
});

Cleanup: Test environments persist on disk. Clear .oso/ directory periodically to free up resources.

Troubleshooting

Dev Server won't start

Port already in use:

# Check what's using port 8080
lsof -i :8080
# Use different port
export OSO_PORT=9000
./oso-dev-server main.polar

Permission error:

Ensure the binary has execute permissions: chmod +x oso-dev-server
Check that the .oso/ directory is writable

Connection issues

SDK can’t connect:

Check server is running: curl http://localhost:8080/api/healthcheck
Check environment variables: echo $OSO_URL $OSO_AUTH
Ensure you’re using the test token: e_0123456789_12345_osotesttoken01xiIn

Docker networking:

Use service names in Docker Compose, not localhost
Verify port mapping: -p 8080:8080

Policy issues

Policy not loading:

Check file path is correct and accessible
Use --watch-for-changes to reload automatically
Check logs for syntax errors

Important notes

Not for production use. The Dev Server is designed for development and testing only.

Version compatibility. Always validate policies against Oso Cloud before deploying.

Data persistence. Dev Server state is stored on disk. Clear .oso/ directory to reset.

Next steps

Write authorization policies using Polar
Model your data as facts for authorization decisions
Implement authorization checks in your application

Get Started

Develop

Deploy and Manage

Quickstart

Why use the Dev Server

Installation options

Docker (Recommended)

Native binary

Environment configuration

SDK configuration

Load your policy

Advanced usage

Troubleshooting

Important notes

Next steps

​Quickstart

​Why use the Dev Server

​Installation options

​Docker (Recommended)

​Native binary

​Environment configuration

​SDK configuration

​Load your policy

​Advanced usage

​Troubleshooting

​Important notes

​Next steps

Quickstart

Why use the Dev Server

Installation options

Docker (Recommended)

Native binary

Environment configuration

SDK configuration

Load your policy

Advanced usage

Troubleshooting

Important notes

Next steps