> _**CLI skill · `code` namespace** · ~5,326 tokens_ # `code` — VS Code in the browser, per container ## Purpose **This is the VS Code IDE running in a browser tab — not a programmatic API.** Open `https://{P}-{C}-code-1.{N}.containers.hoody.icu/?folder=&id=1` and you get the full editor: file tree, diff view, debugger, terminals, extensions marketplace, all backed by the container's filesystem. The public `code-1` URL is served by an **orchestrator** that requires both `folder` and `id` query params on `/` (it boots child editor instance `id` and iframes it from the `{P}-{C}-http-<60000+id>.{N}` subdomain); with neither param it serves the OpenAPI spec, with only one it returns 400. The `code` namespace methods documented here exist mainly to *configure* the editor (open a folder, install an extension, mint a path-proxy URL) — the day-to-day use is "open the URL". Like every Hoody kit URL, `code` is **iframable**: drop the `code-1` URL into an `` — works in any HTML page, mobile browser, Slack URL preview surface, etc. 5. Brand the URL: `hoody proxy create` → `https://agent.proxy.hoody.icu`. Hides the `containerId`; gate via `proxyPermissionsContainer.*` for production. To run two distinct single-extension surfaces under the same container, use different `id` values at the same `code-1` URL (`id=1` for Cline, `id=2` for Continue, etc. — each `id` is its own child editor instance). ### 3. Install and verify a VSIX `hoody code extensions install` / `hoody code extensions list` are spec-only — not implemented by the current kit (see Quirks). Pre-install via the child launch flags or in-editor, then verify on disk (Example 4). ### 4. Tunnel a container port The **child instance** mounts `/proxy/:port` and `/absproxy/:port` at its root (`{P}-{C}-http-<60000+id>.{N}` subdomain); the public `code-1` root does NOT route them. The generated accessors `hoody code proxy-path` / `hoody code proxy` build URLs against `/api/v1/code/proxy/...` which no surface routes — drive path-proxy with raw URLs (`https://{P}-{C}-http-60001.{N}.containers.hoody.icu/proxy/{port}/...`) or the hand-extended embed-URL builder under the `code.vscode` service (see Quirks for `embedUrl`). ### 5. Authenticate password mode Form-POST the password to the **child instance** root `/login` (see Example 7) — the generated `hoody code auth *` accessors build `/api/v1/code/login|logout`, which no surface routes. ## Quirks & gotchas - Login limit 2/min, 12/hr per process. - `/api/v1/code/health` resets idle heartbeat; only `/healthz` excluded. - 3 mount prefixes; use `/api/v1/code`. - `hoody code vs` persists `folder`/`workspace` into `coder.json`; `ew=true` wipes. - `hoody code auth mint-key` idempotent. - `hoody code extensions install` / `hoody code extensions list` are declared in the kit OpenAPI (and surfaced by the generated SDK/CLI) but the current kit does NOT implement them — no extensions router is mounted anywhere; requests fall through (child: vscode catch-all SPA/302; `code-1`: orchestrator plain-text 404). Pre-install via the child launch flags (`--install-extension`, `--install-builtin-extension`, `--preload-builtin-extensions-dir`) or in-editor. - `/proxy/:port` and `/absproxy/:port` are mounted at the **child instance root** (`{P}-{C}-http-<60000+id>.{N}` subdomain), NOT under `/api/v1/code` and NOT at the public `code-1` root — the orchestrator has no proxy routes. Use `https://{P}-{C}-http-60001.{N}.containers.hoody.icu/proxy/{port}/...` (or `/absproxy/{port}/...`). - `/proxy/:port/...` rewrites `req.base` so the upstream sees `/`; `/absproxy/:port/...` keeps the full `/absproxy/:port/...` prefix verbatim — use `absproxy` for APIs/WS where the upstream cares about its own base path. - `hoody code check-update` (the generated accessor — the `update.*` service does not exist) queries GitHub releases. NOTE: the generated path is `/api/v1/code/update/check`, but `/update` is mounted on the **child instance** root only — the generated call and the public `code-1` root both miss it (orchestrator has no `/update` route). Call `https://{P}-{C}-http-<60000+id>.{N}…/update/check` directly. The route returns `{ checked, latest, current, isLatest }`, but the generated TS type `CodeHealthCheckUpdateResponse` (from the OpenAPI spec) mis-declares `{ current, latest, updateAvailable }` and drops `checked` — read `.isLatest`/`.checked` from the raw JSON, not `.updateAvailable`. `?force=true` bypasses the 24 h cache (kit-level only — not exposed via the generated SDK or CLI surfaces; reachable only by raw HTTP to `/update/check?force=true`). - `hoody code health` at the public `code-1` URL hits the ORCHESTRATOR, which returns the standardized 9-field `{ status: "ok", service, built, started, memory, fds, pid, ip, userAgent }` envelope — matching the generated TS type. The flat `{ status: "alive" | "expired", lastHeartbeat }` shape only appears on the child instance's health route (`{P}-{C}-http-<60000+id>.{N}` subdomain). - `kit_slug` always `code`. - `embedUrl` is a hand-extended SDK builder hung off the `code.vscode` service; an equivalent embed builder also exists on the CLI surface. Composes the iframe URL without firing a request. ## Common errors - `hoody code extensions install` / `hoody code extensions list`: not implemented — at `code-1` the orchestrator returns a plain-text Express 404; on the child the request falls through to the vscode catch-all (SPA / 302 / 401). The `MISSING_URL`/`INVALID_URL_FORMAT`/`DOWNLOAD_FAILED`/`INSTALLATION_FAILED` codes exist only in the OpenAPI spec, never at runtime. - Path-proxy 400 `Invalid port`. The cited line only checks `isNaN(port)`; the 1024–65535 range is enforced by the OpenAPI client validator before the request lands. - `/proxy/{port}/` unauth root returns 302 `/login`; deeper 401. - `hoody code auth submit` rate-limit returns HTML, not JSON. - Unauth `hoody code vs` returns 302 `/login`, not 401. - On the **child instance** (`-http-` subdomain) unmatched `/api/v1/code/*` paths fall through to the VS Code app router (`vscode.ts:241` `router.all(/.*/, ...)`), which serves the SPA shell / 401 / 302 depending on auth — NOT a JSON 404. At the public `code-1` URL they return the orchestrator's plain-text Express 404 instead. Test against an explicit known-good path (e.g. `/api/v1/code/health`) for kit liveness. ## Related namespaces → `terminal`, `files`, `exec`, `browser`, `daemon`. ## Examples `code` is a **URL-first** namespace — for most workflows the kit URL itself (with the right query string and / or iframe wrapper) IS the deliverable. The methods here exist to *configure* the editor (install an extension, mint a key, log in), not to drive it. Each example below is a copy-pasteable recipe in the mode you're reading. URL-composition steps are pure string templates and need no kit call. HTTP / SDK steps were verified against the kit source (orchestrator + child-instance routes). Set `P`, `C`, `N` (project id, container id, server name) from `hoody containers get` first. ### 1. Open the editor with a folder pre-loaded — bookmarkable URL **Goal:** ship a teammate a single URL that opens VS Code already pointing at the right repo. `?folder=` is persisted into `coder.json` as the last-opened folder, so even subsequent un-querystringed visits land back on it (until you pass `?ew=true` to clear). ```bash hoody --container "$C" code open 1 --folder /workspace/myrepo --url # `--url` prints the URL instead of launching $BROWSER. ``` To clear the persisted folder later (so the next visit opens the welcome page), append `?ew=true` (`hoody code vs` with `ew=true` wipes `coder.json`). ### 2. Extension-only embed — boot straight into one extension's UI **Goal:** open `code-1` as a single extension's panel — no file tree, no command palette, no marketplace. The whole viewport is that extension. Pair with a folder so the extension opens with the right repo selected. URL pattern (no kit call): ``` https://${P}-${C}-code-1.${N}.containers.hoody.icu/?extension=.&folder=&id=1 ``` ```bash hoody --container "$C" code embed saoudrizwan.claude-dev --folder /workspace/myrepo # emits the extension-only URL. ``` The `extension` query value MUST match `^[a-zA-Z0-9-]+\.[a-zA-Z0-9-]+$` — `publisher.name` only, no version. ### 3. Install a custom VSIX programmatically **Goal:** push an internal extension (`.vsix`) into the container's VS Code. ⚠ **`hoody code extensions install` is spec-only** — the current kit mounts no extensions router, so the documented `POST /api/v1/code/extensions/install` never reaches a handler (`code-1`: orchestrator plain-text 404; child: vscode catch-all SPA/302). What actually works: - **At child boot (launch flags):** `--install-extension `, `--install-builtin-extension `, or drop VSIXes in the preload dir consumed by `--preload-builtin-extensions-dir` (the platform passes `/hoody/storage/hoody-code/extensions` by default). - **In-editor:** Extensions view → `…` menu → "Install from VSIX…" (the VSIX must already be on the container filesystem — push it via the `files` namespace). ### 4. List installed extensions + verify a specific one is present **Goal:** sanity-check after a deploy that the extensions you expected are actually loaded. ⚠ **`hoody code extensions list` is spec-only** (same as `hoody code extensions install` — no extensions router is mounted). Verify on disk instead: each child instance keeps its extensions at `/hoody/storage/hoody-code/data//extensions`, with directory names like `.-`. Run the check inside the container via the `terminal` / `exec` namespaces: ```bash ls /hoody/storage/hoody-code/data/1/extensions # → ms-python.python-2024.0.0 saoudrizwan.claude-dev-3.7.0 … ls /hoody/storage/hoody-code/data/1/extensions | grep -q '^saoudrizwan\.claude-dev-' \ || echo "MISSING: saoudrizwan.claude-dev" ``` (Generated `hoody code extensions list` accessors on any surface target the unimplemented endpoint and return no data.) ### 5. Path-proxy a container port through the editor — `/proxy/{port}` for browser previews **Goal:** surface a dev server (Vite, Next.js, `python -m http.server`) running inside the container at `localhost:3000` to your laptop's browser. `/proxy/{port}` rewrites `req.base` so relative URLs in the upstream HTML still resolve under the proxy prefix — use this for **browser-rendered apps with relative asset paths**. ``` https://${P}-${C}-http-60001.${N}.containers.hoody.icu/proxy/3000/ ``` (`http-<60000+id>` is the **child instance** subdomain — `60001` for `id=1`. The public `code-1` root does NOT route `/proxy`.) ```bash # Hidden CLI commands `hoody code proxy-path` / `hoody code proxy` exist but are # .hideHelp()-gated; the recommended flow is to compose the URL and open it directly: echo "https://${P}-${C}-http-60001.${N}.containers.hoody.icu/proxy/3000/" ``` Port range is `1024–65535`; the kit only enforces `isNaN(port)` at `pathProxy.ts:18` (returns `400 Invalid port`); the 1024–65535 range is enforced by the SDK client validator (`proxy.service.generated.ts:157`) but NOT by the server — raw HTTP callers (curl/fetch) must self-enforce the range. ### 6. Absproxy a container port — `/absproxy/{port}` for raw API / WebSocket passthrough **Goal:** call a JSON API or open a WebSocket running inside the container with the **path preserved verbatim**. Use this — not `/proxy/` — for any case where the upstream cares about the literal request path (REST APIs, gRPC-Web, WebSockets at fixed routes). The `/proxy` variant rewrites `req.base` and will break path-sensitive servers. ``` https://${P}-${C}-http-60001.${N}.containers.hoody.icu/absproxy/8080/v1/items?q=cake ^^^^^^^^^^^^^^^^^ ← upstream sees exactly this path ``` ```bash echo "https://${P}-${C}-http-60001.${N}.containers.hoody.icu/absproxy/8080/v1/items?q=cake" ``` `/proxy` and `/absproxy` share the same auth gate: unauth root returns `302 /login`, deeper paths `401`. ### 7. Authenticate password mode — `hoody code auth login` + `hoody code auth submit` **Goal:** when the kit is launched with `--password ` / `--hashed-password <argon2>`, every route is gated. The login flow is HTML-form-based (not a JSON API): fetch `/login` to bootstrap, then `POST /login` form-encoded to get a session cookie. ```bash # CLI does not expose the raw login form; open `hoody code open 1` in your browser # and complete the login interactively, then re-use the session cookie from the browser. ``` Rate limit: **2/min, 12/hr per process**. Hitting the limit returns HTML, not JSON — tail the body for the literal string `Login rate limited!` (i18n LOGIN_RATE_LIMIT, English locale value). ### 8. Health check + extension verify — post-deploy smoke test **Goal:** after a container rebuild, confirm the `code` kit is up AND the extensions you ship pre-installed actually loaded. One-shot smoke. ```bash hoody --container "$C" code health -o json | jq -r .status # → ok (orchestrator envelope) # Extensions: `hoody code extensions list` targets the unimplemented endpoint (see Example 4); # verify on disk instead via the terminal namespace: # ls /hoody/storage/hoody-code/data/1/extensions ``` ⚠ On the **child instance**, `/api/v1/code/health` resets the idle-shutdown heartbeat — only `/healthz` (kit-internal, not surfaced through the public path) is excluded; hitting it on a cron keeps the child hot. The orchestrator's `code-1` health endpoint does not touch child heartbeats. ### 9. Logout + verify the session cookie is revoked **Goal:** end the password-mode session cleanly when a teammate steps away. `hoody code auth logout` clears the cookie server-side; subsequent requests with the old cookie redirect to `/login`. ```bash # `hoody code auth logout` IS exposed (hidden but functional in cli/commands/code.ts:432); the # alternative is to open the browser session and click Sign Out, # OR drop the cookie file: rm -f /tmp/code-cookie.txt ``` Note: on the child instance, `/api/v1/code` unauth → `302 /login` (NOT `401`); plan your client to follow / catch the redirect rather than expect a JSON `401` body. ### 10. Embed the extension URL in an iframe — drop VS Code into your own page **Goal:** ship a brand-able dashboard / docs site / Notion-style canvas with VS Code (or a single extension) embedded as a panel. The kit URL is iframable; just hand the right `src` and `allow` attributes. ```html <!-- Full editor, with a folder pre-loaded --> <iframe src="https://${P}-${C}-code-1.${N}.containers.hoody.icu/?folder=/workspace/myrepo&id=1" style="width:100%;height:100vh;border:0" allow="clipboard-read; clipboard-write; cross-origin-isolated" ></iframe> <!-- Single extension only (no IDE chrome) — Cline as a service --> <iframe src="https://${P}-${C}-code-1.${N}.containers.hoody.icu/?extension=saoudrizwan.claude-dev&folder=/workspace/myrepo&id=1" style="width:100%;height:100vh;border:0" allow="clipboard-read; clipboard-write" ></iframe> ``` To hide the `containerId` behind a brandable host, wrap the URL with a `hoody proxy create` — the iframe `src` becomes `https://agent.proxy.hoody.icu`, the `containerId` never leaves the server. Gate it via `proxyPermissionsContainer.*` for production (IP allow-list, basic-auth, etc. — see the `api` namespace). The same iframe pattern works for **every** Hoody kit (`files`, `terminal`, `display`, `desktop`, `browser`, `notes`, `workspaces`, …) — compose a full HTML "operating system" out of kit iframes with no native code. ## Reference ### `hoody code` (7) — VS Code server | Command | Aliases | Category | Summary | SDK Link | Example | |---------|---------|----------|---------|----------|---------| | `hoody code auth mint-key` | | write | Generate server web key | `code.vscode.mintKey` | `hoody code auth mint-key` | | `hoody code check-update` | | read | Check for updates | `code.health.checkUpdate` | `hoody code check-update` | | `hoody code embed` | | read | Build an iframeable URL for a VS Code extension (extension-only mode) | `code.vscode.embedUrl` | `hoody code embed rooveterinaryinc.roo-cline` | | `hoody code extensions install` | | write | Install VS Code extension from URL | `code.extensions.install` | `hoody code extensions install --url https://example.com --as-builtin` | | `hoody code extensions list` | ls | read | List installed extensions | `code.extensions.listIterator` | `hoody code extensions list` | | `hoody code health` | | read | Service health check | `code.health.check` | `hoody code health` | | `hoody code open` | | action | Open the Code kit service in your browser | | `hoody code open [index] [--url] [--folder PATH]` |