Reach a Workbench from a Page

Goal: Serve a web page from a hosted workbench, and know what reaches it.

A hosted workbench with its Web mode on runs a web server its author wrote, in its own container. OpenX forwards every request under its address to that server. This page covers what the author writes and what the caller and the server each get. The overview of all three modes is Reach a Hosted Workbench.

The address

https://openx.fathym.com/ox-api/w/<workspace id>/workbenches/<apiSlug>/Web/

<workspace id> is the ID shown in Workspace -> Settings, and the slug in the examples (ui-sample) is a stand-in for your own workbench's APISlug. The root page is .../Web/, with the trailing slash, so the page's relative links resolve under it. A browser that opens .../Web is redirected there (308); a call from code is not redirected and works at both. Every path below the root, such as .../Web/products, goes to the workbench's own fetch handler, with its method, body and query as the caller sent them. The author decides which paths exist and what each answers; OpenX declares no routing. The Web segment is the mode's key and is case-sensitive.

What the author writes

A Web mode is a thin wrapper around Deno.serve. The author gives it one fetch handler:

import { WebMode, Workbench } from '@fathym/fai/workbenches';

async function serve(req: Request): Promise<Response> {
  const url = new URL(req.url);

  if (url.pathname === '/') {
    return new Response('<h1>UI Workbench</h1>', {
      headers: { 'Content-Type': 'text/html' },
    });
  }

  return new Response('Not Found', { status: 404 });
}

export default Workbench('ui-sample').Modes({ Web: WebMode({ handler: serve }) });

The handler gets every request except GET /health, a path the mode reserves for a readiness probe. Any framework works that can return a Response.

Who gets through today

Calls with a key work: a key from APIs -> API Keys, while the workspace's API identity is Team (the default) or Hybrid. It needs no particular access right. Under App Identity, team keys are turned away and a caller needs an access token from an App Identity you trust.

Opening the page in a browser tab with your OpenX sign-in does not work: the door admits a bearer token only, and a browser session is not accepted. A workbench page is reached by code.

const res = await fetch('https://openx.fathym.com/ox-api/w/<workspace id>/workbenches/ui-sample/Web/products', {
  headers: { 'Authorization': `Bearer ${token}` },
});
const html = await res.text();

That works for a back end that fetches a workbench's page to render or send it, for instance as a report.

What the workbench receives

OpenX forwards the request to the container's own address, and the answer streams back. Some things are kept on OpenX's side:

• The caller's Authorization header and OpenX's own x-ox-* and x-oi-* headers (the door's stamps and tokens) are not forwarded, and neither is an Authorization query parameter. The container does not receive the caller's key, and it is not told who the caller was.
• A WebSocket upgrade on any path is carried through to the same path.
• Redirects are passed back as they are, not followed.
• Cookies are kept apart. A cookie the workbench sets is renamed with a prefix for that workbench mode, and its path is moved under the mode's address, so a workbench never reads OpenX's session cookies or another workbench's.
• Two response headers that would reach past the mode's own path on OpenX's address (Clear-Site-Data and Service-Worker-Allowed) are dropped.

Because the container is told nothing about the caller, a page that needs to know who is asking has to sign them in itself, or be reached by a caller that holds the credential it expects.

Building on other workbenches

A Web workbench often reads data from another one. Workbenches Build on Each Other shows how OpenX hands the consumer the address of the one it uses.

One declaration, three modes

Web, API and MCP run on the same hosting: one container per mode behind the same check. Turn on more than one and the same source is a page, a REST API and an MCP server.

If something's off

Issue	Do
401	The key has expired, or the API identity is App Identity, which turns team keys away. Make a new key, or use an App Identity token
404 on a page	Check the address names your workspace id (/ox-api/w/<workspace id>/...). A path the author's handler does not serve answers as the handler decides
404 "Mode 'Web' not enabled"	The workbench has not turned the Web mode on. Add it in the Modes tab and deploy
503 "is not deployed yet"	The mode has no container yet. Deploy the workspace, or wait for a deploy that is running to finish
A page loads but its assets 404	The author's handler serves its own static files. Check the paths it matches
The consumed workbench's address is missing	See Workbenches Build on Each Other for the Consumes tab

Next steps

• Call it from code -> Reach a Workbench over HTTP
• Connect an AI -> Reach a Workbench over MCP
• Host another -> Host Your Own Workbench