---
title: GeoGlyph Gateway API
emoji: 🛰️
colorFrom: pink
colorTo: gray
sdk: docker
app_port: 7860
pinned: false
---

# GeoGlyph Gateway API

FastAPI gateway for GeoGlyph SAM2 running on a Slurm worker.

The gateway does not run SAM2. It:

1. Starts a long-running Slurm worker API with `sbatch`.
2. Opens an SSH tunnel to the worker node.
3. Proxies `/process`, `/status/{task_id}`, and `/download/{task_id}` to the worker.

## Required Hugging Face Space Secrets / Variables

Secrets:

- `SSH_PRIVATE_KEY`: private key allowed to SSH into the cluster login node.
- `GATEWAY_API_TOKEN`: bearer token used by QGIS/client requests.
- Optional `SSH_KNOWN_HOSTS`: known_hosts content for the cluster login host.

Variables:

- `CLUSTER_LOGIN_HOST`: public DNS/IP of the cluster login node, e.g. `kraken.example.edu`.
- `CLUSTER_USER`: cluster username, e.g. `manolo`.
- `CLUSTER_MODEL_DIR`: path to `GeoGlyphFinal/model` on the cluster.
- `WORKER_INFO_DIR`: path where the Slurm worker writes node/port files.
- `WORKER_PORT`: usually `8000`.
- `GATEWAY_LOCAL_PORT`: usually `18000`.
- `SBATCH_SCRIPT`: usually `run_geoglyph_worker_env.sbatch`.

## Endpoints

- `GET /health`
- `POST /worker/start`
- `POST /worker/connect`
- `GET /worker/health`
- `POST /process`
- `GET /status/{task_id}`
- `GET /download/{task_id}`


## SSH authentication options

Preferred for production/prototype stability:
- `SSH_PRIVATE_KEY_BASE64`: base64-encoded private key, single line.

Alternative quick test:
- `SSH_PASSWORD`: cluster password. This requires the Docker image to include `sshpass`. It will not work if the cluster requires MFA or interactive Duo-like prompts.

If both a key and password are configured, the gateway prefers the key.