> _**SDK skill (basic)** · ~26,627 tokens · hoody-sdk v1.0.0-beta.17_ # SDK mode — drive Hoody from TypeScript/JavaScript Typed client, 1000+ methods, 21 namespaces. Node, Bun, browser. Configurable automatic retries, error redaction, async iterators, automatic 401 re-auth, cross-origin auth strip. Tradeoff vs HTTP/CLI: needs JS runtime + `npm install`. ## What is Hoody Hoody is a remote-first computing platform: every workflow — coding, browsing, scheduling, agent runtimes, file storage, GUI desktops, HTTP services, scripts, databases, displays — runs in account-owned cloud containers reachable by URL, with zero local setup. **Thesis: everything remote, no friction.** A container is a **full Linux box (systemd + root, just like a VM — not a Docker-style minimal sandbox)** you can spin up, fill, and use from anywhere; ports are auto-published on `https://...containers.hoody.com`; GUIs render to browser tabs; one-shot scripts mount as HTTP endpoints; databases, terminals, file watchers, full XFCE/MATE desktops, and SSH are first-class kits. Standard distro tooling works as expected — `apt install nginx && systemctl enable --now nginx`, `journalctl`, `crontab`, etc. The CLI / SDK / HTTP surfaces are three skins on the same control + container plane — drive whichever fits your runtime. **Prefer a GUI?** The **Hoody Agent** browser GUI runs at `https://{P}-{C}-agent-1.{N}.containers.hoody.com` — file browser, code editor, agent sessions, PR review, MCP, memory, image-gen, web search, all in a browser tab. It's the human-facing surface over the same `agent` kit these skills drive programmatically (same `-agent-1` host — the HTTP API lives under its `/api/v1/agent/` path). **Every kit URL is also iframable** (`code`, `files`, `terminal`, `display`, `desktop`, `notes`, `agent`, …) — you can compose a full HTML "operating system" out of kit iframes with no native code. Use whichever surface fits the moment. **Need a custom API, script-as-service, or multi-step workflow?** Default to `exec`. Drop a `.ts` / `.js` (or shell-out via Bun) into the scripts dir and it auto-mounts as an HTTP endpoint — no framework, no deploy, schema-validated, logged, metric-instrumented, alias-able to a public hostname. Each script is a micro-service, kept warm by the kit; **multi-step workflows** (call agent A → check with agent B → trigger action C) are just one script orchestrating the steps. (Not a sandbox for untrusted code — see `exec` namespace.) **Need a GET-only URL for something that's actually a POST/PUT?** Use `box.curl.run(...)` (or compose the GET-bridge URL via the kit URL helper). The `curl` kit can turn any REST call into a single GET-able link for browser-only callers, restricted webhooks, agents with web-fetch-only access. See `curl` namespace. **Stuck, or unsure how to do something?** Ask Hoody's public docs assistant — an unauthenticated MCP endpoint at `https://chatbot.hoody.com/mcp` (one tool, `search_hoody_docs`; or the `POST /api/chat` SSE fallback) answers any "how do I…" with cited doc URLs. Use it for discovery when you're not sure which namespace fits. ## Install + import ``` npm install hoody-sdk ``` ```typescript import { HoodyClient } from 'hoody-sdk'; ``` Browser UMD (exposes `window.HoodySDK`): `https://cdn.jsdelivr.net/npm/hoody-sdk/dist/hoody-sdk.browser.min.js`. ## Init With a person present, build the client without a token and sign them in through their browser: `hoody.api.auth.device.start`, give them the link and code, poll `hoody.api.auth.device.poll`, then `hoody.adoptSession(result)` (§ Login). Never ask for their password in chat. For code that already holds a token, or a password login the user runs themselves, pick one of these: ```typescript // Token import { HoodyClient } from 'hoody-sdk'; const hoody = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN! }); ``` ```typescript // Credentials (eager login) import { HoodyClient } from 'hoody-sdk'; const hoody = await HoodyClient.login('https://api.hoody.com', { username, password }); ``` ```typescript // Lazy credentials (login on first call) import { HoodyClient } from 'hoody-sdk'; const hoody = new HoodyClient({ baseURL, credentials: { username, password } }); ``` Retries are on by default. When neither the client nor the call sets `retries`, eligible requests normally get up to two retries, with a 2-second backoff base and at most 10 seconds of total waiting: a GET, HEAD, OPTIONS, PUT or DELETE, or a create whose kit honours an idempotency key (`watch.watchers.create`, `agent.sessions.create`, `notes.nodes.create`; the SDK sends a fresh key when you set none), on `408/425/429/500/502/503/504` or a lost connection; any other method only when the connection could not be opened (the request never reached a server). A kit that is still starting answers `502 BACKEND_GATEWAY_ERROR`; such a request gets up to five retries within the client's `kitStartingWaitMs` (default 20000 ms, `0` turns it off), and when that wait runs out it throws `ApiError` with status 502 and code `KIT_NOT_READY`. Set `retries: 0` to disable retries, or pass `retries` (and optionally `retryDelayMs` / `retryOnStatuses`) to the constructor or per call to set your own budget (250 ms backoff base, no total cap). Connection failures proven never dispatched can be retried for any method. With an explicit retry budget, POST/PATCH can also retry `429` and hoody-files' `409 FILE_PATH_BUSY` refusal (nothing was changed). A streamed body is never replayed; a request marked `responseIsFinal` is replayed only when it never reached a server, and only under an explicit budget. Recommended `baseURL`: `https://api.hoody.com` (when `baseURL` is omitted outside a browser page, `HoodyClient` uses `HOODY_BASE_URL`, then `HOODY_API_URL`, then `https://api.hoody.com`; a client with `target: 'kit'` gets no default host; in a browser page an omitted base stays relative to the page). Realm-scoped: `https://{realmId}.api.hoody.com`. Token scoping → § Auth model. Kit URLs → § Proxy URLs. ## Namespace structure - **`hoody.api.*`** — account-level (auth, projects, containers, realms, vault, wallet, etc.). There is no `hoody.api.billing` namespace; billing endpoints live under `wallet`/`servers`. - **`box..*`** — kit services inside a container (terminal, files, browser, display, exec, sqlite, …). `const box = await hoody.withContainer(container)`. On a 401 the client tries one recovery and, if it succeeds, replays the request once: account calls get a new token from `onTokenExpired` or the client's refresh token / `credentials`; kit calls only recover when you supply `onKitAuthExpired`. Pattern: `client...`. ## Iterator + pagination Most paginated endpoints, page-, offset- and cursor-style alike, ship three flavours (`notes.comments.list` has `listAll` / `listIterator` too): - `list(...)` — one page; pagination shape varies per endpoint. Most container/project list endpoints expose `data.pagination.{total,page,limit,totalPages}`; some kit endpoints expose top-level `meta.page`. - `listAll(...)` — collect all pages. - `listIterator(...)` — an async generator for `for await`, fetches on demand, supports early `break`. Its items are typed with the row type of the list response (a `containers.listIterator()` row has `id`, `name`, `status`, …), so no cast is needed. Default for non-trivial sets. Other paginated methods follow the same `*` / `*All` / `*Iterator` triple (e.g. `containers.listByProject*`, `snapshots.list*`, `projects.listPermissions*`). ## Errors SDK throws **`ApiError`** on every 4xx/5xx, except where the status is the answer: `files.exists` and `sqlite.kv.exists` resolve `false` on a 404 (a missing or expired key). Type guards: `isApiError`, `isRetryableApiError`. Also `ValidationError` (client-side input) and `VaultCryptoError`. Retryable codes: `408/425/429/500/502/503/504`, plus hoody-files' `409 FILE_PATH_BUSY` (see the retry policy under § Init). Secrets (`Authorization`, `Cookie`, `?token=…`, body `{password,token,apikey}`, URL userinfo) auto-redacted to `[REDACTED]` before `catch`. See § Reference appendix. ## Streaming - **SSE / live event endpoints** — some generated SSE methods stream: `box.proxyLogs.stream(...)` and `box.exec.logs.stream(...)` return `Promise>` (`for await (const ev of await box.exec.logs.stream({ file, follow: true })) { ev.event; ev.raw; }`). So does `box.watch.events.stream(id, { since_id })`. Check each SSE method's return type: one that returns a buffered `Promise>` never resolves on a live stream. For those, use the URL with `EventSource`/`fetch`+ReadableStream, or poll the corresponding cursor endpoint. - **WebSocket** — `box.notifications.connect`, `box.terminal.sessions.connect`, `box.curl.jobs.connect` and `box.watch.events.connect` return a wrapper: `await wrapper.connect()` to open, then per-wrapper typed callbacks — terminal exposes `onOutput` (Uint8Array); notifications exposes `onNotification` / `onHeartbeat`; curl exposes `onJobstarted` / `onJobprogress` / `onJobcompleted`; watch exposes `onFileEvent` / `onLag`; lifecycle close on every wrapper is `onDisconnect`. NOT Node-style `.on('message')`. See per-namespace SDK skill. - **Reverse tunnels** — `box.tunnel.expose` / `pull` / `serve` on a container-scoped client; the package-root `tunnelExpose` / `tunnelPull` / `tunnelServe` take an explicit WebSocket URL. Runnable snippets in § Core operations cheat-sheet below. ## Index Recipes: § Core operations cheat-sheet. Per-namespace deep dives: `SKILL-SDK/.md`. --- # Proxy URLs — capability-based per-container routing ## What it is `https://{projectId}-{containerId}-{kit_slug}-{n}.{node}.containers.hoody.com` - Proxy terminates TLS on `*.containers.hoody.com`, parses the hostname segments (project, container, kit, index) and routes to that kit. - Hoody API: global `https://api.hoody.com`. - Aliases (`my-api.{N}.containers.hoody.com`) are shortcuts; canonical URL is authoritative. ## Components | Segment | Meaning | |---|---| | `projectId` | 24-char hex. | | `containerId` | 24-char hex. Bearer credential. | | `kit_slug` | Kit id (see Kit slug table); some namespaces differ from their slug (e.g. `notifications` → `n`, `proxyLogs` → `logs`). | | `n` | 1-based instance index; single-instance kits use `1`. | | `node` | Bare server hostname (use the `server_name` field from container responses). | | Suffix | `.containers.hoody.com` | ## Every kit URL is iframable — compose a UI out of kits Each kit URL serves a regular HTML/JS page (or HTTP/WS API) — drop it into an ` ``` You can compose a **full HTML "operating system" out of Hoody kit iframes** — no native code, no installer, just URLs. Hoody itself does this: `os.hoody.com` is essentially a kit-iframe shell. ### Collaborative embeds — work from inside the chat Most modern collaboration tools accept iframes (or unfurl URLs into rich previews that render iframes), so a Hoody kit URL drops straight into: | Platform | Embed surface | Outcome | |---|---|---| | **Slack** | Canvas embed, custom unfurls, Slack apps | Drop a `terminal-1` URL into a channel canvas → live shell that everyone in the channel can see + drive. Pair with a Cline `?extension=…` `code-1` URL for "agent-in-the-channel" support. | | **Notion** | `/embed` block (paste URL → Embed) | Wiki page that contains the live editor / agent / file browser as part of the doc. | | **ClickUp** | Embed view in any list / dashboard | Project board with the relevant repo's `files-1` and `code-1` panes alongside tickets. | | **Matrix / Element** | `m.html` event, custom widgets | Same as Slack — live terminal / agent in a room. | | **Microsoft Teams / Zoom** | Apps that accept URL iframes | Shared workbench during calls. | | **Discord** | Activity URLs, link previews | Drop the URL; viewers click into the live surface. | | **Confluence / Jira** | "Smart Link" / iframe macro | Runbook page with the live tool baked in. | | **Plain HTML** | `