---
name: eocube-platform-overview
description: "Map of the EOCube.RO earth-observation platform for agents in notebooks.eocube.ro: hosts and endpoints, authentication and storage model, the eocube MCP tools and CLI, which tool to reach for first, and which eocube-* skill to load next for search, data access, publishing, storage, Dask or the meteo cube."
license: Apache-2.0
compatibility: "EOCube.RO JupyterHub notebooks (notebooks.eocube.ro) with the eocube MCP sidecar (eocube-tools 0.2.x). The CLI and Python parts also work on a laptop after `pip install eocube[cli]` and `eocube auth login`."
---

## The platform in one paragraph

EOCube.RO turns Sentinel and other satellite products into analysis-ready data on a
Kubernetes cluster at West University of Timișoara. Users work in JupyterHub notebooks
(`notebooks.eocube.ro`). Data is described in a STAC catalog (`stac.eocube.ro`) and stored
as Cloud Optimized GeoTIFFs and Zarr on S3-compatible object storage. Access is governed by
single sign-on (Keycloak realm `rocs`) and short-lived STS storage credentials.

## Hosts

| Service | URL | Notes |
|---|---|---|
| STAC API | https://stac.eocube.ro | pgstac. CQL2 via the `filter` extension; **no `query` extension**. |
| STAC browser | https://browser.stac.eocube.ro | Human browsing of the same catalog. |
| Primary S3 | https://storage.svc.uvt-01.eocube.ro | Shared data buckets. Path-style, region `ro-west-uvt-01`. |
| Personal S3 | https://s3.svc.uvt-01.eocube.ro | The user's own bucket. Same region and addressing. |
| SSO | https://aai.eocube.ro | Keycloak, realm `rocs`. |
| Docs | https://docs.eocube.ro | Tutorials: STAC search, COG access, two meteo notebooks. |
| Basemap tiles | https://tiles.eocube.ro | Styles at `/assets/styles/light.json`, `/europe.pmtiles`. |
| TiTiler | https://titiler.functions.svc.uvt-01.eocube.ro | Dynamic tiles from COGs. |

## Pod environment

`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN` (STS, renewed by the
hub), `AWS_DEFAULT_REGION=ro-west-uvt-01`, `AWS_VIRTUAL_HOSTING=FALSE`, `AWS_S3_ENDPOINT`
(host without scheme), `ROCS_AAI_ACCESS_TOKEN` / `ROCS_AAI_REFRESH_TOKEN`,
`DASK_GATEWAY__ADDRESS` and friends, `MODEL_ID=rocs_qwen3`. Sidecars on `127.0.0.1`
(LLM proxy `:9112`, embedder `:9113`, MCP `:8000`) exist only in notebook pods, never on
Dask workers.

## The eocube MCP server (first choice for lookups)

Server `eocube` at `http://127.0.0.1:8000/mcp`. Tools never raise; a failure is
`{"ok": false, "error": ...}`. Large results are written to a file and the tool returns
its path (under `~/.eocube/mcp-artifacts/`); those files are disposable scratch outputs.
If a returned path does not exist in the notebook, ask for `inline=true` or smaller
results, or use the Python client instead.

| Family | Tools | Reach for it when |
|---|---|---|
| Identity | `auth_whoami` | Before any write: it tells you the username that must go into `eocube:owner`. |
| STAC read | `stac_list_collections`, `stac_get_collection`, `stac_get_item`, `stac_search` | Finding data. `stac_search` takes collections, bbox, datetime/start/end/`last_days`, ids, `intersects`/`intersects_file`, `sortby`. It has **no CQL2 filter**; see `eocube-stac-search`. |
| Geography | `geo_county_by_name`, `geo_county_by_mnemonic`, `geo_admin_unit_by_name`, `geo_admin_unit_by_code` | Turning "Timiș county" or a SIRUTA code into GeoJSON; the default result is a file path you pass as `intersects_file`. |
| Validation | `stac_validate_item`, `stac_validate_collection` | Always before `stac_add_item` / `stac_create_collection`. |
| Raster | `raster_discover_files`, `raster_build_stac_item` | Building items from local GeoTIFFs. Hrefs come out as local relative paths: rewrite them after upload (`eocube-stac-publish`). |
| Ingest | `extract_sentinel1_slc`, `extract_sentinel2_l1c` | STAC items from raw Sentinel products on disk. |
| STAC write | `stac_create_collection`, `stac_update_collection`, `stac_add_item`, `stac_update_item` | Publishing. No delete tools are registered; deletion is CLI only, with confirmation. |
| Storage | `storage_ls` | Quick read-only listing of the user's storage. Uploads and downloads are CLI or Python. |

## The eocube CLI and Python package

- `eocube auth info|login|get-storage-credentials --as-json`: identity and STS credentials.
- `eocube services stac search|download|collection …|item …`: catalog from the shell;
  `services stac download dataset.json` is the bulk asset downloader.
- `eocube services storage ls|upload|download|rm|share|check`: object storage.
- `eocube services geospatialorg …`: the same admin-unit lookups as the `geo_*` tools.
- `eocube doctor`: first thing to run when something returns 403.
- Python: `from eocube.integrations.notebooks import setup_notebook, sign_in_place,
  setup_personal_cluster, fs, user_fs`.

## Rules

- Use the platform stack: pystac-client, geopandas, rioxarray, xarray, dask, `eocube`.
  Never issue raw `requests` calls against the STAC API.
- Prefer MCP tools over shell for STAC and geography lookups.
- Never delete or overwrite user files; confirm before any destructive STAC or storage
  operation.

## Which skill next

| You need to | Load |
|---|---|
| find items in the catalog | `eocube-stac-search` |
| open or download the assets you found | `eocube-data-access` |
| publish your own collection or items | `eocube-stac-publish` |
| move files to or from object storage, mint credentials | `eocube-storage-cli` |
| scale computation across workers | `eocube-dask` |
| daily temperature or precipitation grids for Romania | `eocube-meteo-cube` |
| verify the skills loader | `eocube-skills-probe` (only on its token) |