Skip to main content
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. 
# 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/api/healthcheck

​
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"
);

​
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

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.
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/

# 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.
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

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
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 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