Oso Dev Server

Run Oso Cloud locally for faster development and testing.

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:

curl http://localhost:8080/health

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

oso.js

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

const oso = new Oso(
  "http://localhost:8080",
  "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/health
• 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