OpenIndustrial Documentation
Menu

Workbenches

Goal: Host any workbench in your workspace and make it discoverable by any AI.

What is a workbench?

A workbench is a git repository that declares one or more modes — each mode is a way to expose the workbench's capabilities to clients.

The SurfaceWorkbench node type lets you drop a workbench onto any surface in your workspace, point at its repo, and hit Deploy. OpenIndustrial clones the repo, builds an image per enabled mode, provisions a container per mode, and routes traffic to each mode at a stable URL.

What ships in this release

  • MCP Mode. Host the workbench's tools, prompts, and resources as an MCP server. Any AI agent (Claude, Cursor, ChatGPT, ...) connects via standard MCP HTTP-Streamable transport at <your-workspace-url>/oi-api/workbenches/{APISlug}/MCP. See MCP access →.
  • API Mode. Auto-expose every tool method as a REST endpoint at <your-workspace-url>/oi-api/workbenches/{APISlug}/API/{tool}/{method}. Any HTTP client (curl, Postman, fetch, backend integrations) connects with a Bearer JWT; the workspace API Explorer surfaces a per-workbench route catalog with copy-paste curl examples. See API access →.
  • Web Mode. Host an author-authored HTTP server (HTML pages, SSR, static assets, whatever the author writes) as a workspace-routed page at <your-workspace-url>/oi-api/workbenches/{APISlug}/Web/. See Web access →.
  • Composition (Consumes primitive). A workbench can declare dependencies on other workspace workbenches, and OpenX wires their proxied URLs into the consumer container as WB_CONSUMED_${alias}_URL env vars at deploy. See Composition (Consumes) →.

What's coming

  • Workflow Mode, Vault Mode, and other community-authored modes.

The hosting infrastructure is mode-agnostic from day one — a new mode type added to the workbench holon system is hostable with zero platform changes.

Core concepts

APISlug

Every hosted workbench has a required APISlug — a DNS-label-safe string, unique in your workspace, that you set in the inspector Hosting tab. It's the workbench's public handle: it fills the URL path (/oi-api/workbenches/{APISlug}/{mode}), the MCP tool/resource namespace, and the container name. Your AI clients address the workbench by its APISlug; internal node lookups are the system key.

Each enabled mode runs its own container (shared image where Dockerfiles match). There is no cross-surface sharing.

The mode model

Workbench holons declare tools once, then enable one or more modes to expose them. The same .Tools({...}) declaration serves MCP tools when MCPMode is enabled AND serves REST routes when APIMode is enabled — one workbench, multiple client protocols. WebMode adds an author-authored HTTP server as a third client shape:

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

async function serve(req: Request): Promise<Response> {
  // Author-authored HTML/JSON/whatever routes for Web mode.
  return new Response('<h1>UI</h1>', { headers: { 'Content-Type': 'text/html' } });
}

Workbench('alerting')
  .Tools({ CreateRule: createRuleTool, ListRules: listRulesTool })
  .Modes({
    MCP: MCPMode(),                    // exposes each tool method as an MCP tool
    API: APIMode(),                    // auto-exposes each tool method as POST /{tool}/{method}
    Web: WebMode({ handler: serve }),  // runs the author's fetch handler as a workspace-routed page
  });

The inspector's Modes tab shows the modes the workbench declares. You toggle which ones OpenIndustrial hosts. MCP mode is enabled by default.

Source, Ref, Entry

  • Repo — the workbench git repo URL (https://github.com/my-org/my-workbench).
  • Ref — a branch, tag, or commit sha. A branch redeploys the latest commit each deploy; a tag or sha pins an immutable build. There is no latest keyword.
  • Entry — the path inside the repo to the .ts file that exports the workbench definition (e.g. packages/my-workbench/workbench.ts).
  • Dockerfile — optional. When omitted, OpenIndustrial generates a default Dockerfile (Deno + fai; CMD fai run <Entry> --mode "$FATHYM_OX_WORKBENCH_MODE" --config /fathym-ox/mode-config.json).

Management is EaC-driven

Thinking Tip:

Workbench management does not go through a REST API. You configure workbenches via the inspector (Source / Modes / Hosting tabs); the inspector writes into Everything-as-Code, and the platform's actuator applies your changes at deploy time. See the REST API reference for the surrounding resource-level API.

This mirrors how connections, simulators, and warm queries are managed — declare intent in the workspace record, hit Deploy, and the platform reconciles.

Governance

Every request to a hosted workbench MCP endpoint is governed:

  • Authentication — Bearer JWT required on every request.
  • Authorization — the caller must hold the Workspace.Workbench.Host access right.
  • Audit — every proxied call is logged with caller, workbench APISlug, mode, and timestamp.
  • Isolation — each enabled mode runs in its own container; cross-workbench and cross-workspace traffic is isolated at the routing layer.

Your workbench is not a shared tool pool. It's a per-workbench MCP server behind your workspace's governance boundary. Each AI client connects directly to the workbench URL it needs, with its own JWT.

Where to go next

If you want to...Go to...
Point OpenIndustrial at your workbench repoInstall a workbench from source →
Connect Claude, Cursor, or ChatGPT to a hosted workbenchMCP access →
Call a hosted workbench's tools via RESTAPI access →
Browse a hosted workbench's web UIWeb access →
Compose one workbench with another (Consumes)Composition (Consumes) →
Understand the surrounding workspace APIREST API reference →
See how MCP works at the workspace levelMCP Integration →
On this page