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

# Run StateSet Warehouse locally

> Start the WMS with PostgreSQL, explore synthetic warehouse work, and verify an authenticated facility read.

Start from a checkout of `stateset-warehouse`. Use Rust **1.90+**, Node.js **22.12+**, npm,
and Docker Compose for the development PostgreSQL service. PostgreSQL **12+** is supported;
the included Compose service uses PostgreSQL 16.

**Working surface:** local WMS dashboard and REST API.**Bring:** repository access and an isolated development database.**Finish with:** a visible synthetic facility and a verified identity/facility read.

## Start the synthetic workspace

Run from the Warehouse repository root, copying the example configuration on a fresh checkout:

```bash theme={null}
cp .env.example .env
docker compose up -d postgres
npm --prefix dashboard ci
bash scripts/dev.sh
```

Open **[http://127.0.0.1:3012](http://127.0.0.1:3012)**, then select **Open synthetic demo**. The API listens at
**[http://127.0.0.1:8088](http://127.0.0.1:8088)**. The example configuration enables `WMS_DEMO=true` and points at
PostgreSQL on port `5548`.

The demo persists synthetic changes in its own database tenant and refuses external event
receivers. There is no in-memory fallback. Stopping the development script stops its API and
leaves PostgreSQL running.

```bash theme={null}
curl --fail-with-body --silent --show-error http://127.0.0.1:8088/ready
```

A successful readiness response establishes database connectivity. In the dashboard, review
the selected facility, inventory, receipts, and orders before practicing a receive, move,
or pick. Keep synthetic work separate from operational inventory.

## Configure an empty real workspace

Stop the development script. In `.env`, set `WMS_DEMO=false` and configure individual
credentials through `WMS_API_KEYS_JSON`. Each secret must be at least 32 characters:

```dotenv theme={null}
WMS_DEMO=false
WMS_API_KEYS_JSON={"replace-with-a-random-secret-of-at-least-32-characters":{"tenant":"your-org","actor":"operator:alice","role":"admin"}}
```

Use your actual secret in local configuration or a secret manager, then restart
`bash scripts/dev.sh`. This configuration is for API-key mode; WorkOS sign-in needs its own
organization mappings and deployment setup.

Real tenants start with an empty `MAIN` warehouse and receiving/staging bins. Administrators
configure the facility, products, and storage locations, then record actual receipts or
reasoned opening counts. Additional facilities have independent inventory and work.

## Verify identity and facility

Set `WMS_TOKEN` in your shell to an existing configured credential. These are reads:

```bash theme={null}
export WMS_API_URL=http://127.0.0.1:8088

curl --fail-with-body --silent --show-error "$WMS_API_URL/v1/session" \
  --header "Authorization: Bearer $WMS_TOKEN"

curl --fail-with-body --silent --show-error "$WMS_API_URL/v1/warehouses?limit=100" \
  --header "Authorization: Bearer $WMS_TOKEN"
```

Confirm the returned tenant, actor, role, and `default_warehouse_id`. Read that exact ID;
do not infer the active facility from directory sort order:

```bash theme={null}
export WMS_WAREHOUSE_ID=wh-main

curl --fail-with-body --silent --show-error \
  "$WMS_API_URL/v1/warehouses/$WMS_WAREHOUSE_ID" \
  --header "Authorization: Bearer $WMS_TOKEN"
```

**Checkpoint:** the authenticated session identifies the intended tenant and
actor, and the facility snapshot supplies its current version and inventory/work state.

## Serve a built dashboard

From the Warehouse repository, after stopping the development API:

```bash theme={null}
npm --prefix dashboard run build
cargo run --locked
```

Open **[http://127.0.0.1:8088](http://127.0.0.1:8088)**. Remote deployments require HTTPS, configured credentials,
PostgreSQL backup/restore, and physical reconciliation. Local synthetic checks do not establish
facility acceptance.

Continue with [REST and MCP](/stateset-warehouse/api-and-mcp) or
[connect Sync, Warehouse, and Freight](/guides/oms-wms-tms).


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