> ## 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](/develop/local-dev/env-setup) before setting up the Dev Server.
</Note>

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

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="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")
    )
    ```
  </Tab>
</Tabs>

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

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="Policy issues">
    **Policy not loading:**

    * Check file path is correct and accessible
    * Use `--watch-for-changes` to reload automatically
    * Check logs for syntax errors
  </Accordion>
</AccordionGroup>

## Important notes

<Warning>
  **Not for production use.** The Dev Server is designed for development and testing only.
</Warning>

<Warning>
  **Version compatibility.** Always validate policies against Oso Cloud before deploying.
</Warning>

<Warning>
  **Data persistence.** Dev Server state is stored on disk. Clear `.oso/` directory to reset.
</Warning>

## Next steps

* [Write authorization policies](/develop/policies/overview) using Polar
* [Model your data as facts](/develop/facts/overview) for authorization decisions
* [Implement authorization checks](/develop/enforce/authorize-requests) in your application