Hydra Uandai

SKILL.md

---

name: hydra-uandai

description: Hydra/Uandai platform — configure API access, package OpenClaw workspace zip, upload agents, list subscriptions, invoke runs.

metadata: {"openclaw":{"requires":{"env":["HYDRA_API_KEY","HYDRA_API_BASE_URL","HYDRA_API_ORIGIN"]},"primaryEnv":"HYDRA_API_KEY","homepage":"https://api.uandai.ai/docs/programmatic-api"}}

---



# Hydra / Uandai (packaging + programmatic API)



**Bundled docs version:** 2026.06.09



Use this skill for **all** Hydra/Uandai automation: first-time setup, workspace packaging, upload, subscriptions, and invocation.



## First-time setup (chat → persist)



When the user sends a **configure Hydra** message with settings, or env vars are missing:



1. Parse from the user message (setup-only; do not repeat key in later work prompts):

   - `HYDRA_API_ORIGIN` — API host without `/api` (e.g. `https://api.uandai.ai` or `http://127.0.0.1:8000`)

   - `HYDRA_API_BASE_URL` — API prefix with `/api` (e.g. `https://api.uandai.ai/api`)

   - `HYDRA_API_KEY` — full `hyd_live_…` from hydra-app → Settings → API Keys

2. Install the **full skill folder** (`SKILL.md` + `references/`) under `~/.openclaw/skills/hydra-uandai/` (preferred) or `<workspace>/skills/hydra-uandai/` for local dev.

3. Merge into `~/.openclaw/openclaw.json` under `skills.entries["hydra-uandai"]`:



```json5

{

  skills: {

    entries: {

      "hydra-uandai": {

        enabled: true,

        apiKey: "hyd_live_…",

        env: {

          HYDRA_API_KEY: "hyd_live_…",

          HYDRA_API_BASE_URL: "https://api.uandai.ai/api",

          HYDRA_API_ORIGIN: "https://api.uandai.ai",

        },

      },

    },

  },

}

```



4. Do **not** echo the full API key back. Tell the user to run `/new` or restart the gateway.

5. Optional smoke test: exchange → `GET /v1/auth/me`.



**Security:** Prefer a private OpenClaw session for setup messages that contain the key. After setup, operational prompts need no key and no doc URLs.



## Before any Hydra action



**Read bundled reference files in this skill directory first.** Do not rely on `web_fetch` unless the user explicitly pastes a Hydra doc URL in the current message.



| Task | Read |

|------|------|

| Package workspace zip | `references/agent-packaging.md` |

| Exchange, upload, invoke | `references/programmatic-api.md` |



Optional live refresh: if the user pastes `{HYDRA_API_ORIGIN}/docs/agent-packaging` or `/docs/programmatic-api` in chat, you may `web_fetch` that URL and prefer it for that session.



Default prod origin: `https://api.uandai.ai`



## Required inputs before API calls



Do **not** call Hydra business endpoints until all required inputs for that endpoint are known.



| Source | Examples |

|--------|----------|

| Env / config (setup once) | `HYDRA_API_*`, exchanged `access_token` |

| User message (every operation) | `agent_name`, `description`, `subscription_price`, `default_model_identifier`, provider test values, invoke `configs` |

| Prior API response | `agent.id`, `revision_no` from upload; activations list for invoke |



If any **user-sourced** field is missing or ambiguous:



1. Ask the user in one concise message listing only missing fields.

2. **Do not** call the endpoint with placeholders, defaults, or guesses.

3. Confirm values briefly (never echo secrets).



Per-endpoint prerequisite tables and checklists: `references/programmatic-api.md`.



## Packaging (OpenClaw workspace → zip)



Stable rules (full steps in `references/agent-packaging.md`):



1. **Never** zip the live workspace root directly

2. **Staging:** copy to `output/<agent>-workspace/` with exclusions → validate → zip **staging contents only**

3. **Output:** `output/<agent-name>-workspace.zip`

4. **Hydra zip layout:**

   - Personality files (`SOUL.md`, `IDENTITY.md`, …) at **zip root**

   - No extra parent wrapper folder in the archive

   - `SKILL.md` only at `skills/<id>/SKILL.md`, `workspace/skills/<id>/SKILL.md`, or zip root

   - Exclude `node_modules/`, `.env`, `logs/`, `memory/`, `.openclaw/`, `output/`, **`hydra-uandai/`** — max **50MB**

5. **Do not include this skill in the upload zip.** Install on the trainer machine at `~/.openclaw/skills/hydra-uandai/` (full folder with `references/`). A copy under `<workspace>/skills/hydra-uandai/` is for local dev only — exclude it when packaging.

6. Report: `📍 Path: MEDIA:<path-to-zip>`



Common failures: personality only under `workspace/`; nested wrapper folder; misplaced `skill/SKILL.md`; **`hydra-uandai/` in zip** (`openclaw_bundle_platform_skill`).



## API authentication (exchange required)



Raw API keys work **only** on exchange:



```http

POST /v1/auth/token

Authorization: Bearer $HYDRA_API_KEY

```



Alternative on exchange only: `X-Hydra-Api-Key` or JSON `{ "api_key": "…" }`.



Response: `{ "access_token", "refresh_token", "user" }` — cache in session memory.



**All other calls:** `Authorization: Bearer <access_token>`



On access expiry: `POST /v1/auth/refresh`. On refresh `401`: re-exchange if key still active; else user creates a new key in Settings.



Do **not** send `$HYDRA_API_KEY` on upload, invoke, or list endpoints.



## Workflows



**Trainer — publish end-to-end:** setup (if needed) → read `references/agent-packaging.md` → package zip → read `references/programmatic-api.md` → **collect upload metadata from user** (see prerequisites) → exchange → `POST /v1/agents/upload` → return `agent.id` and `agent.revision_no` → optional `POST /agents/{id}/proposals`



**Trainer — upload only:** collect required upload fields from user → exchange → `POST /v1/agents/upload` with multipart: `bundle` (zip) + `agent_name` + `description` + `subscription_price` + `default_model_identifier` + provider `config_data_type_json` / `test_values_json` (see `references/programmatic-api.md`; Ollama needs `OLLAMA_KEY` + `OLLAMA_URL`)



**Subscriber — discover:** exchange → `GET /v1/me/subscriptions` → `GET /v1/me/activations?invokable_only=true`



**Subscriber — invoke:** exchange → `GET /v1/me/activations?invokable_only=true` → **collect `configs` from user** (and confirm `agent_id` / `revision_no`) → `POST /v1/executions` → poll `GET /v1/executions/{run_id}` until terminal



## Safety



- Never log or echo the full API key

- On `401`: refresh → re-exchange → key may be revoked

- On `402`: user needs credits

- API keys cannot create/revoke other keys (Settings / password JWT only)