> ## Documentation Index
> Fetch the complete documentation index at: https://www.osohq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> [!NOTE]
>
> **First time?** Install the [CLI and editor tools](https://www.osohq.com/docs/develop/local-dev/env-setup.md) before setting up the Dev Server.

## Quickstart

Start the Dev Server using Docker:

```bash theme={null}
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)

```bash theme={null}
# 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:

```bash theme={null}
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](https://ui.osohq.com/install).

**macOS/Linux:**

```bash theme={null}
# 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:

```bash theme={null}
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.

> [tab] Node.js
>
> ```javascript title="oso.js" theme={null}
> const { Oso } = require("oso-cloud");
>
> const oso = new Oso(
>   "http://localhost:8080",
>   "e_0123456789_12345_osotesttoken01xiIn"
> );
> ```

> [tab] Python
>
> ```python title="oso.py" theme={null}
> from oso_cloud import Oso
>
> oso = Oso(
>     url="http://localhost:8080",
>     api_key="e_0123456789_12345_osotesttoken01xiIn"
> )
> ```

> [tab] Go
>
> ```go title="oso.go" theme={null}
> 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:

```bash theme={null}
# Start with a policy
./oso-dev-server main.polar

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

## Advanced usage

> [accordion] Docker Compose integration
>
> Run alongside your app in local development:
>
> ```yaml theme={null}
> 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.

> [accordion] Configuration options
>
> Customize the Dev Server behavior with environment variables:
>
> ```bash theme={null}
> # 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:
>
> ```bash theme={null}
> # Reset Dev Server state
> rm -rf .oso/
> ```

> [accordion] Pin Dev Server versions in CI
>
> ```bash theme={null}
> # 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.

> [accordion] Parallel test environments
>
> Create isolated test environments for parallel integration tests:
>
> **Create new environment:**
>
> ```bash theme={null}
> # 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:**
>
> ```javascript theme={null}
> 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

> [accordion] Dev Server won't start
>
> **Port already in use:**
>
> ```bash theme={null}
> # 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

> [accordion] 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`

> [accordion] 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

> [!WARNING]
>
> **Not for production use.** The Dev Server is designed for development and testing only.

> [!WARNING]
>
> **Version compatibility.** Always validate policies against Oso Cloud before deploying.

> [!WARNING]
>
> **Data persistence.** Dev Server state is stored on disk. Clear `.oso/` directory to reset.

## Next steps

* [Write authorization policies](https://www.osohq.com/docs/develop/policies/overview.md) using Polar
* [Model your data as facts](https://www.osohq.com/docs/develop/facts/overview.md) for authorization decisions
* [Implement authorization checks](https://www.osohq.com/docs/develop/enforce/authorize-requests.md) in your application


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.