# Unified deployment notes

This package is intentionally the same source tree for the Hugging Face Space
and the school server.  Deployment settings, not separate code branches,
select the data plane.

## School server

Set `MARINE_API_URL=http://127.0.0.1:8000` and
`MARINE_PROXY_UPSTREAM_URL=http://127.0.0.1:8000`.  If local data mirrors are
available, set `LOCAL_SQUID_DATA_ROOT=/data0/zqyan/squid_data/raw` and
`LOCAL_TUNA_DATA_ROOT=/data0/zqyan/tuna_data/raw`. These are read-through
caches: a same-path local file is preferred, while every missing file is read
from the configured Hugging Face Dataset. Do not set different repository
names on the two deployments.

Set the browser-facing export base before restarting the school UI:

```bash
export PUBLIC_BASE_URL="https://subway-unbiased-barcode.ngrok-free.dev/marine"
```

This prevents localhost download links. Public exports then use
`/marine/download/<token>` through the fixed ngrok UI endpoint.

The public ngrok URL exposes the UI on `/` and the Marine API through
`/marine/*`.  Therefore its health endpoint is `/marine/health`, not `/health`.

## Hugging Face Space

Set the following Variables:

- `MARINE_API_URL=https://subway-unbiased-barcode.ngrok-free.dev/marine`
- `CODEX_PROVIDER=zai`
- `CODEX_MODEL=glm-5.3`
- `CODEX_HARNESS_RUNTIME=native`
- `REQUIRE_CODEX_HARNESS=1`

Set these Secrets:

- `ZAI_API_KEY`
- `CODEWHALE_RUNTIME_TOKEN`
- `HF_TOKEN` when the fisheries datasets require authenticated reads

Do not set `MARINE_PROXY_UPSTREAM_URL` or local data-root variables in the
Space.  They belong only to the school server.

## Runtime behavior

The following read-only requests bypass the model and are returned by the
application directly: greetings, runtime identity, Marine health, and
metadata-only Tuna/Squid file inventories.  This makes these operations fast
and avoids the non-interactive MCP approval problem.

Actual Ocean exports and fisheries content analysis remain guarded operations
through the official Codex CLI Harness. `CODEX_ALLOW_MCP_BYPASS` is forbidden:
startup fails if it is enabled. The model receives only the read/query/export
Marine MCP allow-list; it has no shell, arbitrary filesystem, process-control,
Git-write or deletion tool. Server maintenance belongs to a separate SSH
super-administrator workflow, not to chat.

## Multi-day Ocean downloads

The unified build adds `mcp_marine_marine_export_range`. It creates one real
download for each day in an inclusive date range and returns all URLs. A single
request is capped at 31 days to protect the Ocean API; request longer periods
month by month. Set `MARINE_EXPORT_RANGE_MAX_DAYS` only to a value from 1 to 31
(default: 31).