# Volcano Sdk

> Use for any request to build, create, extend, debug, or deploy an app, website, backend, API, or function using Volcano, even when the user does not mention the SDK. Entrypoint and router; always pair with volcano-platform and the applicable domain skills.

- Skill: `kong/volcano-sdk` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kong/volcano-sdk`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kong/volcano-sdk/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Kong (https://skillmd.com/u/kong)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kong/volcano-sdk

---

# Volcano SDK Entrypoint

## Before anything else: ensure the Volcano CLI is present

Every Volcano build and deploy goes through the `volcano` CLI, so make sure it
is present and up to date before writing or deploying anything:

- Run `which volcano`.
  - **Found:** run `volcano upgrade` to keep it on the latest version. This is
    a harmless, best-effort refresh — it no-ops when already current. Treat any
    failure (e.g. a transient network/GitHub hiccup) as a no-op and continue:
    the installed CLI still works, a failed upgrade is never a blocker, and it
    is not worth troubleshooting.
  - **Missing:** fetch
    `https://raw.githubusercontent.com/Kong/volcano-cli/main/docs/installation.md`
    (plain Markdown, readable without the CLI) and run whichever install method
    it documents that matches a package manager already on `PATH` — check
    `which npm`, `which pnpm`, `which bun`, `which brew` in that order, and only
    use the documented manual `curl` install if none are present. A fresh
    install is already the latest version. Re-run `which volcano` to confirm.

These are well-known commands to run as-is, not a script to reconstruct. Don't
assume a package manager that isn't installed, and don't invent steps beyond
what that doc lists. The `install-volcano` skill exposes this same flow as an
explicit command.

## Role
This skill is the **entrypoint and router** for Volcano SDK work. It is intentionally slim: it tells you the mandatory rules that apply to every Volcano build, and which other `volcano-*` skill to use based on the task at hand. Don't try to do deep work from this skill alone — use the relevant domain skill(s) first.

## Mandatory Pairing — `volcano-platform`
**Always read `volcano-platform` alongside this skill.** It covers the canonical project shape, function deployment model (`volcano/functions/`), migrations, `volcano-config.yaml`, environment variables, shared-code conventions, and the deploy workflow. Without `volcano-platform` you cannot produce a deployable codebase.

If `volcano-platform` content is not visible in your context, read or invoke it through the current host's skill mechanism before continuing.

**Note:** `volcano init` creates a minimal runtime skeleton (`volcano/` dir with env files, migrations, and — for language templates — a starter handler and config). Build on top of that skeleton by following `volcano-platform`. Do not expect `volcano init` to produce the complete project structure.

## Mandatory Usage (volcano-standard template)
When building on the Volcano platform you MUST use:
- **Volcano Auth** (`volcano.auth.*`) for ALL authentication and user identity.
- **Volcano Database query builder** (`volcano.from('table').select()`) for persistent storage, with RLS policies. Direct Postgres access inside Functions is a discouraged, last-resort exception for the query builder's specific gaps (joins/upserts/multi-statement transactions) — never a default — see `volcano-database`.
- **Volcano Functions** for ALL privileged or secret-bearing server-side logic.
- **Volcano Storage** (`volcano.storage.*`) for ALL file operations.
- **Volcano Realtime** (`VolcanoRealtime`) for ALL live update patterns.

Do NOT implement custom alternatives — no custom JWT auth, no ad-hoc database layers, no hand-rolled file storage, no DIY WebSocket multiplexers.

## Skill Router — pick the skill(s) you need

| Task signal | Invoke skill | What it covers |
|---|---|---|
| User accounts or identity, email or password sign-up/sign-in, OAuth, sessions, anonymous users, password recovery, private or per-user data | `volcano-auth` | Full auth API surface, lifecycle, common-error catalog |
| Stored or persistent data, CRUD, records, todos, chat messages, polls, analytics, counters, click tracking, CMS content, feature flags, leaderboards, RLS | `volcano-database` | Query builder + every operator + RLS pattern + limitations (no joins / upserts / multi-statement tx) |
| Volcano Functions, server-side or privileged logic, QR/PDF generators, secrets, outbound third-party APIs, orchestration, scheduled processing, file/image processing | `volcano-functions` | Invocation contract `{data, status, headers, version, error}`, Volcano Functions response shape, handler templates |
| Uploads, downloads, galleries, file sharing, buckets, paths, public/private files, visibility, resumable uploads | `volcano-storage` | Full storage API + access policies + resumable protocol + limits |
| Realtime or live updates/results, collaborative boards, chat, presence or online users, polls, leaderboards, Postgres changes, broadcast, WebSockets | `volcano-realtime` | All three channel types + lifecycle + Browser Origins/CORS gotcha + `accessToken` vs `getToken` decision |
| Next.js or web apps/pages, dashboards, boards, galleries, full-stack UIs, public routes, redirects, webhook ingress, middleware, API routes, server actions | `volcano-nextjs` | Cross-cutting Next.js patterns including the cookie-sync prerequisite |
| TypeScript types — `User`, `Session`, `AuthResponse`, `QueryBuilder<T>`, `StorageObject`, `PostgresChange`, `PresenceState`, `JsonValue`, etc. | `volcano-typescript` | Canonical type definitions for every SDK surface |
| Loading/error/data state, `useApiCall<T>` hook, `fetchWithRetry` with backoff, centralized `handleApiError` dispatcher | `volcano-error-handling` | Reusable error-handling INFRASTRUCTURE (per-domain error MESSAGES live in the relevant domain skill) |
| Project shape, function deployment model, migrations, `volcano-config.yaml`, env vars, deploy workflow, RLS helpers (`auth.uid()`/`auth.email()`/`auth.role()`) | `volcano-platform` | Already mandatory — see "Mandatory Pairing" above |

### How to use the router
1. Read the user's request and identify which task signal(s) match.
2. Read or invoke each matching skill through the current host's skill mechanism BEFORE writing implementation code. Use the exact hyphenated skill names. It's normal to use 2-4 skills for a single task (e.g., a "user dashboard" might need `volcano-auth` + `volcano-database` + `volcano-nextjs`).
3. If the task is purely about project setup (no app features yet), `volcano-platform` alone is enough.
4. If you can't decide between two domain skills, invoke both — token cost is much lower than implementing the wrong pattern.

## Universal Response Pattern
Every SDK method returns `{ data, error }` (auth methods also include `user`/`session`; functions add `status`/`headers`/`version`). Always check `error` before consuming `data`. Do NOT wrap SDK calls in try/catch expecting throws — the only SDK method that throws is `await channel.subscribe()` for realtime.

```ts
const { data, error } = await volcano.from('posts').select('*');
if (error) {
  // dispatch via handleApiError (see volcano-error-handling)
  return;
}
// data is safe to use
```

For comprehensive error-handling infrastructure (centralized dispatcher, React hooks, retry with backoff), use `volcano-error-handling`.

## Forbidden Patterns (always)
These apply to every Volcano build, regardless of which domain skills are loaded:

- Do NOT use `jsonwebtoken` directly — use Volcano Auth.
- Do NOT use `bcryptjs` directly — use Volcano Auth's password handling.
- Do NOT use `pg`/`pg-pool`/`DATABASE_URL` — use `volcano.from(...)` (with `VOLCANO_DATABASE`) instead. Direct Postgres access is a discouraged, untested-surface-area last resort — see `volcano-database`'s "Direct Postgres Access" section before ever reaching for it.
- Do NOT mix `NEXT_PUBLIC_*` env vars into function/server code, or `VOLCANO_*` (un-prefixed) into browser code.
- Do NOT place service keys (`sk-*`) in browser code — the SDK throws if you do.
- Do NOT expect `VOLCANO_API_URL`, `VOLCANO_ANON_KEY`, or `VOLCANO_DATABASE` to be auto-injected into functions — deploy them via `volcano variables deploy` (local) or `volcano cloud variables deploy` (cloud).
- Do NOT skip `await volcano.initialize()` before user-scoped flows in the browser.
- Do NOT use `.ts`/`.tsx` extensions in TypeScript imports — extensionless relative imports only.
- Do NOT use bare `uid()` in RLS policies — always use the schema-qualified `auth.uid()`.

For the deeper context behind any of these (why and what to do instead), the relevant domain skill or `volcano-platform` covers it.

## Output Requirements
At the end of each Volcano build response:
1. **Summarize affected domains** — which `volcano-*` areas were touched (auth/database/functions/storage/realtime/nextjs).
2. **Summarize dependency / env / init changes** — new packages, env vars added, init order changes.
3. **Report validation results** — what you ran (`npm run typecheck`, `npm run build:functions`, local stack health check), what passed, what couldn't be run, and any remaining risk.

## Companion Skills (full inventory)
Always available; invoke as needed:
- `volcano-platform` — mandatory pairing.
- `volcano-auth`, `volcano-database`, `volcano-functions`, `volcano-storage`, `volcano-realtime`, `volcano-nextjs` — domain skills.
- `volcano-typescript` — canonical type definitions.
- `volcano-error-handling` — reusable error-handling infrastructure.

## Optional Fallback Reference