WorkOS Docs Homepage
FGA
API referenceDashboardSign In
Getting StartedOverviewOverviewQuick StartQuick StartPlaygroundPlaygroundKey ConceptsSchemaSchemaWarrantsWarrantsResourcesResourcesPoliciesPoliciesQuery LanguageQuery LanguageWarrant TokensWarrant TokensOperations & UsageOperations & UsageManagementSchema ManagementSchema ManagementLocal DevelopmentLocal DevelopmentIdentity Provider SessionsIdentity Provider SessionsModelingOrg Roles & PermissionsOrg Roles & PermissionsCustom RolesCustom RolesGoogle DocsGoogle DocsEntitlementsEntitlementsUser GroupsUser GroupsManaged Service ProviderManaged Service ProviderAttribute-Based Access ControlAttribute-Based Access ControlConditional RolesConditional RolesPolicy ContextPolicy ContextPublic AccessPublic AccessSuperusersSuperusersBlocklistsBlocklists
API Reference
API Reference
Events
Events
Integrations
Integrations
Migrate to WorkOS
Migrate to WorkOS
SDKs
SDKs

Local Development

Learn how to setup your local development environment with FGA using the FGA Dev Docker image for isolated testing and schema development.

On this page

  • Overview
    • Managed FGA Instance
    • Local FGA Instance
  • Prerequisites
  • Running fga-dev Locally
    • Option 1: Using Docker Compose (Recommended)
    • Option 2: Running a Docker Container
  • Best Practices

Overview

When developing with FGA, you can either connect to a managed WorkOS FGA instance or run a local FGA instance using the fga-dev Docker image. Each option has its own advantages depending on your workflow. This guide will help you choose the best approach and walk you through setting up a local instance if that fits your needs.

Managed FGA Instance

Best for testing against production-like infrastructure and when you need persistent, shared data.

ProsCons
Data persists and is accessible by multiple clientsData is shared (multiple consumers can overwrite each other’s data)
Uses production infrastructure for performance and reliabilityConsumes operation credits

Local FGA Instance

Best for isolated development and testing especially when you want to avoid using operation credits or need a clean environment for each run (such as in CI).

ProsCons
Isolated test environmentYou must manage setup and teardown of data
Does not use operation creditsUses local resources and is not scalable

The fga-dev Docker image provides a fully self-contained FGA environment using SQLite and local caching. This setup is not intended for production but is fine for local development, CI, and integration testing. It is less scalable than the managed instance because it cannot handle high concurrency, complex models, or large datasets.

This guide will show you how to use the fga-dev Docker image to spin up an isolated FGA instance on your machine.

Prerequisites

To start this guide, you’ll need:

  • Docker installed on your machine
  • A WorkOS account (for API keys)
  • Your WorkOS API Key

Running fga-dev Locally

Option 1: Using Docker Compose (Recommended)

Create a docker-compose.yaml:

docker-compose.yaml
version: '3.8'
services:
fga-dev:
image: public.ecr.aws/workos/fga-dev:latest-arm64
user: root # Run as root to avoid permission issues with mounted volumes (non-production only)
volumes:
- fga-dev-volume:/data:rw,cached # Persist data between runs
ports:
- '8001:8001'
environment:
FGA_DEV_PORT: 8001
FGA_DEV_AUTH_API_KEY: <your_workos_api_key> # Your staging WorkOS API key to authenticate the dev image
FGA_DEV_TEST_API_KEY: test_key # A mock API key to authenticate FGA requests from your application
volumes:
fga-dev-volume:

Usage

  1. Start the server:

    docker compose up -d
  2. Configure your app:

    • Point your application’s WorkOS SDK or CLI to the proper host.

    • Use test_key as the API key for FGA requests from your app.

      EnvironmentAPI Host
      Local machinehttp://localhost:8001
      Separate Docker containerhttp://host.docker.internal:8001
      Same Docker Compose networkhttp://fga-dev:8001

If you’re using the WorkOS SDK, you can set the API Hostname option to point to your local FGA instance. Since each SDK instance supports only one API Host, you may need to create a separate SDK instance specifically for FGA when testing against the local service.

  1. Develop:

    Apply schemas, create warrants, and test locally. All data persists in the Docker volume.

    See Schema Management for how to apply a schema to your local instance and test authorization checks.

  2. Shut down:

    docker compose down
  3. Clear all data (optional):

    docker volume rm fga-dev-volume

Tip: Add a secondary Docker Compose service to seed your local instance with test data on startup.

Option 2: Running a Docker Container

You can also run the fga-dev image directly using docker run if you prefer not to use Docker Compose.

docker run -d \
--name fga-dev \
-p 8001:8001 \
-e FGA_DEV_PORT=8001 \
-e FGA_DEV_AUTH_API_KEY=<your_workos_api_key> \
-e FGA_DEV_TEST_API_KEY=test_key \
-v fga-dev-volume:/data:rw \
--user root \
public.ecr.aws/workos/fga-dev:latest-arm64

To stop and remove the container:

docker stop fga-dev && docker rm fga-dev

To remove the volume and reset all data:

docker volume rm fga-dev-volume

Best Practices

Consider the following best practices to ensure a smooth local development experience with FGA:

  • Isolate test data: Use unique resource IDs to avoid collisions which is especially critical when working with shared or managed instances.
  • Automate environment setup: Script the schema and warrant creation on first startup. This makes your development and CI pipelines more reliable and repeatable.
  • Clean up regularly: Tear down and reset your environment when needed to avoid stale data and hidden state, which can lead to confusing behavior.
  • Choose the right environment: Use a managed instance for shared, persistent testing; use the local fga-dev container for isolated development or CI.
© WorkOS, Inc.
FeaturesAuthKitSingle Sign-OnDirectory SyncAdmin PortalFine-Grained Authorization
DevelopersDocumentationChangelogAPI Status
ResourcesBlogPodcastPricingSecuritySupport
CompanyAboutCustomersCareersLegalPrivacy
© WorkOS, Inc.