# Run a local offline sandbox

From a repository checkout with dependencies installed (`uv sync`), run:

```bash
uv run python scripts/run_local_sandbox.py
```

Open `http://127.0.0.1:8000/docs` for interactive Swagger, `/redoc` for the
reference, or `/api/docs` for static/agent discovery. `--port` changes the local
port; `--data-dir` accepts an empty directory. By default the launcher creates
a fresh temporary directory and prints its path. It never resets an existing
database. Keep real customer inputs out of this disposable evaluation state.

This runs the production composition, validation, resolver, enrichment, persistence,
receipts, rate limiting and usage ledger. It uses SQLite locally; shared production
uses its configured database and Redis. The launcher ignores process environment,
`.env` and secret directories, disables network registries and models, and loads
only the checked-in official Scottish Refugee Council enrichment snapshot.
No paid provider credentials are loaded. The fixture is dated, not a live lookup
or a coverage benchmark. The API also mounts the authenticated MCP endpoint at
`/mcp`; the bootstrap `dev-local` credential is accepted by REST only. Use a
persisted API key for remote MCP requests.

The development-only `dev-local` credential works on this loopback listener.
This is local operator access, not an activated public 1,000-credit trial. The
normal ledger reports modeled credits, with no purchase or provider charge.

```bash
curl --fail-with-body http://127.0.0.1:8000/v1/resolve \
  -H 'Authorization: Bearer dev-local' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: sandbox-company-1' \
  --data '{"name":"Scottish Refugee Council","country":"GB",
    "registration_number":"SC145067","jurisdiction":"GB","depth":"research"}'
```

The first request creates a local entity from the submitted identifier and
enriches it with the exact-ID feed: income GBP7,194,086 and 94 average employees,
for the legal entity from 2024-04-01 through 2025-03-31. It reports `new_entity`,
not an independently verified candidate match. No revenue is invented. Provenance
retains source URLs, licence and measurement period. The checked-in
`data/charity-ngo-source-snapshot-2026-09-06/manifest.json` records source artifacts
and hashes; `docs/CHARITY-DATA.md` explains the filed accounts and OGL attribution.

Repeat the identical keyed request to exercise safe operation retry. Read its
`/v1/decisions/{decision_id}` receipt with the same bearer header. Submit a name
absent from the local catalogue to see an unverified local `new_entity`, without
registry identity or enrichment; this sandbox cannot research arbitrary
organizations. A local entity ID is not an accepted real-world match.
Read source readiness at
`/v1/reference/enrichment-fields`. The [MCP guide](/api/mcp) shows equivalent
`resolve_company` arguments for the embedded MCP endpoint. The sandbox does not
simulate provider intelligence or remote OAuth consent.
An idempotent retry returns the original operation's usage receipt without a new
ledger charge; do not sum repeated copies of that receipt as new spending.

Unkeyed exact-content replay is also free, but a prior novel mint can be withheld
when it does not meet the current candidate-match confidence floor. Do not treat
an initial `new_entity` as a guarantee of subsequent accepted-match confidence.

Stop with Ctrl-C. The database remains in the printed directory for inspection;
each launch requires a new empty directory. Its transient erasure key is not a
production recovery mechanism. [API operations](/api/operations) describes the
separate worker and deployment setup. Contract parity does not imply identical
data, performance, topology or live-provider answers.