# sovereign cloud — docs (agent form)

This is the same content as https://cloud.ness2u.xyz/docs, served as Markdown when the
request's `Accept` does not include `text/html` (curl, HTTP clients, agents). The explicit
form is `GET /docs.md`.

## Progressive discovery

1. `GET https://cloud.ness2u.xyz/api/services` — the live catalog: every service with
   `id`, `category`, `tagline`, `status` (`active|partial|planned`), `audience`
   (`everyone|users|operators`), public `url`, and `health` (`up|down|unknown`, cached
   ~5 min; `cache_ttl_secs` and `generated_at` say how fresh).
2. Every service answers `GET {url-origin}/health` → `{ "service", "version", "build", "status" }`.
3. Services that expose KPIs do so at `GET /cp/metrics` (role-scoped by your token).
   `GET https://cloud.ness2u.xyz/api/metrics` aggregates them. **What each tier sees**
   (2026-08-28): *public* — only `*.status`; *user* — your own things (`storage.my_tenant`,
   `rendezvous.my_drops`, `aureum.kbs` = the KBs visible to you) plus shared platform
   *status* that names nobody (en-wiki's cache size stays here: it is the state of a shared
   appliance, not anyone's data); *admin* — platform-wide counts (`identity.accounts`,
   `portal.services`, …). A count of other people's things is never a user-tier metric.

## The protocol, in one breath

A Cluster is just a Node with aggregated promises. Every participant exposes one
Gateway (`scd`) that authenticates peers, advertises a capability tree progressively,
and brokers long-running Invocations under explicit Contracts — it never executes work
itself. Trust before topology, topology before capability, capability before execution.

## Identity — one token for everything

Accounts are issued by the operator (registration is closed). The covenant gateway is
`https://covenant.ness2u.xyz`.

- Humans: sign in at `/login` (optionally `?redirect_uri=…` → returned as `#token=…`);
  manage password and API keys at `/account`; `/logout?redirect_uri=…` ends the session.
- Programmatic login: `POST /v1/identity/login` `{ "username", "password" }` → `{ "token" }`
  (Ed25519-signed, ~24 h, verified locally by every service against `GET /v1/identity/pubkey`).
- Long-lived keys for tools and agents: create an `sck_…` API key on `/account` and send it
  as `Authorization: Bearer sck_…` anywhere a token is accepted (`user` scope).
- `GET /v1/identity/me` with a bearer → who you are, scopes, expiry.

Agents don't get passwords — a human (or parent agent) *vends* them a scoped, short-lived
child token (`POST /v1/identity/vend`); attribution always resolves back to the root human.

## Storage — `https://storage.ness2u.xyz`

S3-compatible object storage (ness2u storage) on the operator's own drives behind a cloud
edge cache. Browser and control plane at `/ui`; the S3 endpoint and per-tenant credentials
are vended against your covenant identity (you need a storage tenant — ask the operator).

```
# your S3 credentials (bearer = covenant token or sck_ key)
curl -s -X POST https://storage.ness2u.xyz/v1/credentials -H "Authorization: Bearer $T"
# → {"endpoint":"https://storage.ness2u.xyz","region":"sovereign-zone-1","bucket":"<tenant>-…","access_key_id","secret_access_key"}
curl -s https://storage.ness2u.xyz/v1/buckets -H "Authorization: Bearer $T"          # your buckets
# a share link: verbose PAR + (with share:true) a short rendezvous link that hides the layout
curl -s -X POST https://storage.ness2u.xyz/v1/buckets/<bucket>/presign -H "Authorization: Bearer $T" \
  -H 'Content-Type: application/json' -d '{"key":"path/file.bin","expires_secs":3600,"share":true}'
```

Any S3 client works with those credentials (`aws s3 --endpoint-url https://storage.ness2u.xyz …`,
rclone, s3cmd); bucket names are prefixed with your tenant name.

## LLM inference — `https://llm.ness2u.xyz`

The model fleet is served by `loch-nessh`, a VRAM-aware broker in front of every model
(chat, reasoning, vision/audio-multimodal, image and video generation). Same bearer as
everything else (token or `sck_` key). SC issues identity; the broker verifies it locally —
SC is never in the inference data path.

OpenAI-compatible:

```
curl https://llm.ness2u.xyz/v1/chat/completions \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model": "qwen3-6-35b-a3b", "messages": [{"role":"user","content":"hello"}]}'
# streaming: "stream": true   ·   2025 Responses API: POST /v1/responses
```

Async claims — the broker's native shape; long jobs survive disconnects:

```
POST   /v1/request             → 202 { claim_id, session_id }
GET    /v1/wait/{claim_id}     → chunked tokens (resumable)
GET    /v1/claims/{claim_id}   → state / result / route_reason
DELETE /v1/claims/{claim_id}   → cancel
```

- Model catalog with context windows and modalities: `GET /app/api/sense/models` (bearer).
- Prefer the `-any` names (`qwen3-6-35b-a3b-any`, `gemma4-e4b-any`, `npu-llama32-1b-any`):
  the broker picks the replica. Steer with `X-Loch-Preference: time|cost` and identify
  yourself with `X-Loch-Caller: <you>`.
- Harness configs generated from the live fleet: `GET /app/api/harness/{opencode|oh-my-openagent|zed}`
  (bearer). The files never contain a credential — export your key as `LOCH_NESSH_API_KEY`
  (opencode) or `OPENAI_API_KEY` (Zed).

## Agents — the Henge and Hospitium

`https://henge.ness2u.xyz/app` is the Agent Console (Now · Agents · Work · Record · Interop),
tenancy-scoped per user. Agent-to-agent interop is over **A2A** at the Hospitium gateway —
ask the catalog (`/api/services`, id `ipsa-agent`) for the current URL; guest sessions and
tracked tasks are documented there. Preview status: shapes may change.

## Rendezvous (drop it, pick it up, gone)

- `https://rendezvous.ness2u.xyz` — `POST /v1/drop` with your token or `sck_` key:
  `{"url": "https://…"}` (pick-up 302s there) or `{"body": "…", "content_type": "…"}`
  (pick-up serves it), plus `ttl_secs` (default 1 h, max 7 d) and `reads` (default 1 =
  burn after reading; 0 = unlimited). Response carries `id` and the pick-up `url`
  (`GET /d/{id}`, anonymous). Tiny blobs only (8 KiB) — for files, drop a storage share link.

## origo (where an address comes from)

- `https://origo.ness2u.xyz` — members only (your token or `sck_` key, `user` scope):
  `GET /v1/ip/{ip}` (geo + ASN), `/v1/ip/{ip}/country`, `/city`, `/geo` (country, region, city,
  latitude/longitude, zip, time zone), `/asn` (number, name, CIDR); `GET /v1/me` (your own address);
  `POST /v1/lookup` `{"ips": [...], "sources": ["geo","asn"]}` (at most 1,000). A miss answers `null`.
  `/v1/sources` gives each dataset's release date. Only `/v1` is routed; everything else answers 404.
- **Try it here:** [mission control → origo](/p/origo), once signed in. It has one address or a batch, every view,
  "my address", and the `curl` for each call. Addresses: IPv4, or IPv6 in any spelling; mapped, 6to4 and Teredo
  addresses answer from the IPv4 address inside them.
- origo uses the IP2Location LITE database for [IP geolocation](https://lite.ip2location.com).

## Knowledge & search

- en-wiki — `https://ness2u.xyz/wiki` — all of English Wikipedia served locally from the
  multistream dump. Public, no token needed.
- Knowledge bases (aureum) — `https://aureum.ness2u.xyz/` (user scope, via portcullis): the KB
  picker; each KB at `/kb/<name>/…` (`/info`, `/query`, `/article/{slug}`, `/entities/…`), resolved to
  the live in-cluster service so links survive moves. Admin CRUDL at `/api/kbs` once aureum ships its
  registry endpoint.
- Search (SearXNG) — internal today; operators reach it at `https://search.ness2u.xyz`
  (admin scope). Public/user exposure waits on a reliable upstream-engine set.

## Operations (operators)

- Mission control: `https://cloud.ness2u.xyz/control` (any account; admin tiles by scope).
- Plexus, the measured cluster state: `https://plexus.ness2u.xyz` (admin scope).
- Runbooks (storage layout transactions, peer whitelisting, backup & restore) — to be written.