Embed a kit UI in your own page
Section titled “Embed a kit UI in your own page”Every Kit service with a browser UI serves it at a URL on the computer. Build the URL of one view, such as a file open in the editor or a read-only terminal, and put it in an iframe on your page. The CLI, SDK and plain HTTP build the same URL from one published catalog.
You need a computer and a signed-in CLI or an API token in HOODY_TOKEN (quickstart); set COMPUTER_ID to the computer’s ID. The HTTP tab also uses curl and jq.
# Print the URL of a file open in the editor. Without --url, the CLI opens it in your browser.hoody files open --computer "$COMPUTER_ID" --view editor --path /home/user/app/server.ts --urlimport { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });const COMPUTER_ID = process.env.COMPUTER_ID!; // your computer's IDconst box = await client.withComputer(COMPUTER_ID);
// One function per view: embeds.<kit>.<view>(target, options). On a withComputer() client the target can be left out.const url = box.embeds.files.editor(undefined, { params: { path: '/home/user/app/server.ts' } });# The three computer fields the host is built fromread -r PROJECT_ID COMPUTER_ID SERVER < <(curl -s "https://api.hoody.com/api/v1/computers/$COMPUTER_ID" \ -H "Authorization: Bearer $HOODY_TOKEN" | jq -r '.data | "\(.project_id) \(.id) \(.server_name)"')
# The view's path, required parameters and flags, from the construction catalogcurl -s https://docs.hoody.com/embeds/catalog.v1.json | jq '.views["files.editor"] | {path, required, flags}'
echo "https://$PROJECT_ID-$COMPUTER_ID-files-1.$SERVER.computers.hoody.com/home/user/app/server.ts?edit="Open the URL in a browser or use it as an iframe src:
https://PROJECT_ID-COMPUTER_ID-files-1.SERVER.computers.hoody.com/home/user/app/server.ts?edit=--url prints the URL and opens and starts nothing. In plain HTTP, follow the catalog’s build rules.
In the Hub, open Computers, pick the computer and open the Connect tab. Under Program links, use the copy icon next to a program to copy its instance 1 address. To frame another view or add parameters, build the URL with the CLI or SDK.
Choose a kit and view
Section titled “Choose a kit and view”A view is one page of a service’s UI, named <kit>.<view>: files.editor, terminal.session, sqlite.tables. Naming only the kit selects its default view. The SDK requires a parameter for the defaults of code, files, run and exec; otherwise it throws an EmbedValidationError with code REQUIRED_MISSING. Without parameters, the CLI opens the root view for code and files.
| Kit | Default view | Other views |
|---|---|---|
terminal, a web terminal session | terminal.session | none |
desktop, a graphical desktop | desktop.session | none |
agent, the agent’s interface | agent.webui | none |
display, the viewer for one display | display.client | none |
browser, the browser service | browser.status | display |
code, a VS Code editor | code.editor | root, extension |
files, the file manager | files.folder | root, editor, search |
notes, Hoody Notes | notes.home | 12 more, for notebooks, pages and settings |
sqlite, the SQLite studio | sqlite.overview | tables, query, kvStore, history, pragmas |
notifications, recent notifications | notifications.landing | none |
pipe, pipe send and receive pages | pipe.send | noscript, progress, video, share, receive |
cron, the crontab manager | cron.manager | none |
run, application search results | run.results | none |
watch, an information page | watch.index | none |
exec, pages your scripts serve | exec.script | none |
http, https, your app on a port | http.content, https.content | none |
Each kit’s open help lists its views and flags (hoody db open --help for SQLite, hoody open --help for http and https). In the SDK, box.embeds.listViews('files') lists a kit’s views, default first, and box.embeds.getUrl('sqlite', undefined, { view: 'tables', params: { table: 'users' } }) builds a view chosen at run time.
The instance number in the hostname (terminal-2) is the CLI’s positional number and the SDK’s index option:
hoody terminal open 2 --computer "$COMPUTER_ID" --read-only --font-size 14 --urlconst terminal = box.embeds.terminal.session(undefined, { index: 2, params: { readonly: true, fontSize: 14 } });echo "https://$PROJECT_ID-$COMPUTER_ID-terminal-2.$SERVER.computers.hoody.com/?readonly=true&fontSize=14"https://PROJECT_ID-COMPUTER_ID-terminal-2.SERVER.computers.hoody.com/?readonly=true&fontSize=14Frame a view
Section titled “Frame a view”<iframe src="https://PROJECT_ID-COMPUTER_ID-files-1.SERVER.computers.hoody.com/home/user/app/server.ts?edit=" style="width: 100%; height: 640px; border: 0"></iframe>On Kit service UI pages the proxy sends Content-Security-Policy: frame-ancestors, which allows any origin by default; on the agent, only its web UI gets it. The proxy replaces the frame-ancestors directive the service sends and keeps the service’s other directives. A service page that refuses framing (frame-ancestors 'none' or X-Frame-Options: DENY) keeps its refusal.
A page your own application serves on an http-{port} or https-{port} URL keeps whatever headers the application sends, and a page a script serves can set its own. Pages that must never be framed keep refusing: a notebook export keeps its own policy.
Each view in the catalog has a frameable value. A yes view can be framed wherever the framing policies that apply to it allow. A no view refuses framing; open it in a new tab instead.
What an embed URL refuses
Section titled “What an embed URL refuses”For a service’s own views, the builders refuse three kinds of parameter the service would read:
| Kind | Examples | Instead |
|---|---|---|
| Credentials and sign-in state | Tokens, passwords, SSH or proxy credentials | Sign-in pages are not embed views. |
| Parameters that change state | A command for the terminal to run, a startup script, a restart, a download trigger | Use the service’s HTTP API. |
| Parameters the platform sets | The terminal or display number | The hostname already selects it. |
Each refusal is an error with a code, never a silently dropped parameter. In the SDK it is an EmbedValidationError; the CLI prints it and exits 1.
box.embeds.getUrl('terminal', undefined, { query: { cmd: 'ls' } });// EmbedValidationError: PARAM_EXCLUDED: cmd cannot be set in an embed URL (mutating)Three views are outside these rules. http.content and https.content show your own application, so the builder passes any query you give it, credentials included. exec.script runs your script when the URL is opened and hands it the query parameters; see exec.script for exceptions.
Opening some other views starts something: a shell, a desktop, the editor, or receiving on a pipe. The reference marks them “starts a process” or “changes state”, and lists each kit’s refused parameters and every error code.
How the URL is built
Section titled “How the URL is built”Every embed URL has the shape of any service URL:
https://{projectId}-{computerId}-{segment}.{serverName}.{computersDomain}{path}?{query}| Part | Rule |
|---|---|
segment | The service and its instance number, such as files-1 or terminal-2. The number is 1 or more, up to a bound per service that the catalog publishes. An index outside the bounds is refused, never rounded. |
computersDomain | Comes from the API base URL: https://api.hoody.com gives computers.hoody.com. The catalog’s domain section lists every rule in order. |
path | The view’s path, with path parameters encoded as the catalog states. A file path keeps its slashes and percent-encodes each segment. |
query | Only parameters the view accepts. Booleans are true or false, and a flag such as edit is sent as edit=. |
A terminal number is 1 to 9999. Numbers 4501 to 5000 are reserved for agent sessions and the proxy refuses them as terminal numbers. The SDK refuses a number above 9999 with INDEX_OUT_OF_RANGE.
Open a view through an alias
Section titled “Open a view through an alias”Pass the alias object that POST /api/v1/proxy/aliases returns as the target, with a program and index matching the view’s. The builder uses the alias’s address as the host:
box.embeds.cron.manager({ alias: 'jobs', program: 'cron', index: 1, url: 'https://jobs.SERVER.computers.hoody.com' });// https://jobs.SERVER.computers.hoody.com/For your application’s HTTP port, open the computer’s Ports & addresses tab in the Hub, select Create alias, enter the port and alias, then select Create alias. This form does not create Kit service aliases. For the cron alias above, use POST /api/v1/proxy/aliases with program: 'cron' and index: 1.
The CLI has no alias target; build alias URLs with the SDK or the catalog. Most Kit UIs read their own identity from the hostname, so their views are refused with ALIAS_VIEW_UNSUPPORTED. The reference’s Alias column shows which views accept one.
Advanced
Section titled “Advanced”- Build without a client:
buildEmbedUrl(kit, computer, options)builds a URL from a computer’sid,project_idandserver_name, for a browser page or other code with no client. Pass the API base URL or computers domain as the fourth argument, for examplebuildEmbedUrl(kit, computer, options, { baseUrl: 'https://api.hoody.com' }). Always supply this configuration when building public Hoody URLs. See SDK and catalog. - The construction catalog:
/embeds/catalog.v1.jsonholds every build rule and view, for building URLs in any language. See SDK and catalog. - Extra query parameters in the CLI: repeatable
--query-param key=valueadds a parameter theexecordisplayview accepts as-is. A JSON-object parameter such as the terminalthemehas no flag; set it in the SDK. See CLI open commands. - One command for every kit:
hoody open <kit> [index]runs that kit’sopen, andhoody open http 8080orhoody open https-8443opens your application on a port. See CLI open commands. - Browser instance start:
hoody browser openstarts the browser instance before opening its page, unless you pass--no-start. See CLI open commands. - A VS Code extension alone:
hoody code embed <publisher.name>prints thecode.extensionURL, which opens the editor focused on one extension. Seecode.extension. - Pipe page links: direct pipe links, and
autostart, which the builder refuses, are on the Pipe page. Their access rule and name limits are in pipe page links. - Notes in a frame: a framed Notes page may keep a cache separate from Notes in a tab, depending on the browser. See
notes.
Reference
Section titled “Reference”The embed URLs reference holds view parameters, error codes, and CLI and catalog details.
What’s Next
Section titled “What’s Next”- Kit services describes what each service does once its UI is open.
- Proxy covers aliases, custom domains and permission rules for the URLs you embed.
- Security explains the open-by-default model and how to lock a computer down before sharing it.