Skip to content

Beta: these docs are still being updated. The next full update is on 19 November at 8 PM UTC. Docs in beta. Full update 19 Nov, 8 PM UTC.

Hoody.com

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.

Terminal window
# 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 --url

--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.

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.

KitDefault viewOther views
terminal, a web terminal sessionterminal.sessionnone
desktop, a graphical desktopdesktop.sessionnone
agent, the agent’s interfaceagent.webuinone
display, the viewer for one displaydisplay.clientnone
browser, the browser servicebrowser.statusdisplay
code, a VS Code editorcode.editorroot, extension
files, the file managerfiles.folderroot, editor, search
notes, Hoody Notesnotes.home12 more, for notebooks, pages and settings
sqlite, the SQLite studiosqlite.overviewtables, query, kvStore, history, pragmas
notifications, recent notificationsnotifications.landingnone
pipe, pipe send and receive pagespipe.sendnoscript, progress, video, share, receive
cron, the crontab managercron.managernone
run, application search resultsrun.resultsnone
watch, an information pagewatch.indexnone
exec, pages your scripts serveexec.scriptnone
http, https, your app on a porthttp.content, https.contentnone

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:

Terminal window
hoody terminal open 2 --computer "$COMPUTER_ID" --read-only --font-size 14 --url
<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.

For a service’s own views, the builders refuse three kinds of parameter the service would read:

KindExamplesInstead
Credentials and sign-in stateTokens, passwords, SSH or proxy credentialsSign-in pages are not embed views.
Parameters that change stateA command for the terminal to run, a startup script, a restart, a download triggerUse the service’s HTTP API.
Parameters the platform setsThe terminal or display numberThe 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.

Every embed URL has the shape of any service URL:

https://{projectId}-{computerId}-{segment}.{serverName}.{computersDomain}{path}?{query}
PartRule
segmentThe 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.
computersDomainComes from the API base URL: https://api.hoody.com gives computers.hoody.com. The catalog’s domain section lists every rule in order.
pathThe view’s path, with path parameters encoded as the catalog states. A file path keeps its slashes and percent-encodes each segment.
queryOnly 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.

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.

  • Build without a client: buildEmbedUrl(kit, computer, options) builds a URL from a computer’s id, project_id and server_name, for a browser page or other code with no client. Pass the API base URL or computers domain as the fourth argument, for example buildEmbedUrl(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.json holds 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=value adds a parameter the exec or display view accepts as-is. A JSON-object parameter such as the terminal theme has no flag; set it in the SDK. See CLI open commands.
  • One command for every kit: hoody open <kit> [index] runs that kit’s open, and hoody open http 8080 or hoody open https-8443 opens your application on a port. See CLI open commands.
  • Browser instance start: hoody browser open starts 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 the code.extension URL, which opens the editor focused on one extension. See code.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.

The embed URLs reference holds view parameters, error codes, and CLI and catalog details.

  • 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.