OpenIndustrial Documentation
Menu

Install a workbench from source

Goal: Point OpenIndustrial at your workbench repo, hit Deploy, and end up with a hosted MCP endpoint your AI agents can use.

Prerequisites

  • Workspace admin access to at least one surface.
  • The Workspace.Workbench.Host access right on your account.
  • A workbench git repo, either your own or an existing one (e.g. github.com/fathym-deno/hello-workbench).
  • The repo's Entry path — the module that exports the workbench (e.g. workbenches/hello/local.ts).
Thinking Tip:

Trying this the first time? Point at github.com/fathym-deno/hello-workbench with Ref main and Entry workbenches/hello/local.ts — it's a working sample that returns "Hello, <your-name>!" over MCP.

Step 1: Drag a SurfaceWorkbench onto a surface

Open the surface where you want the workbench to live and drag SurfaceWorkbench from the surface palette onto the canvas.

Surface palette showing the SurfaceWorkbench node type

The node starts in Pending state with no APISlug set. You'll fill in the details before deploying.

Step 2: Point at your workbench repo

Open the inspector and go to the Source tab. Enter:

FieldValue
Repohttps://github.com/my-org/my-workbench
Refv0.1.0 — a branch, tag, or commit sha
Entrypackages/my-workbench/workbench.ts — path to the workbench definition
Dockerfile(optional; leave blank for the OpenIndustrial default)
Inspector Source tab with Repo, Ref, Entry, and optional Dockerfile fields
Thinking Tip:

Leave the Dockerfile field blank if you don't have one. Typing anything and then clearing it is the same as leaving it blank — the platform normalizes empty strings to absent. When absent, OpenIndustrial generates a default Dockerfile (Deno + fai) that runs your Entry.

About Ref:

  • A branch (e.g. main) redeploys the current HEAD each time you Deploy.
  • A tag (e.g. v0.1.0) or commit sha pins an immutable build.
  • There is no latest keyword.

Step 3: Set the APISlug

Switch to the Hosting tab. Enter an APISlug — a memorable, DNS-safe name like alerting or pricing-tools, unique in your workspace. It's the public handle for the workbench's URLs and MCP namespace.

Inspector Hosting tab with the APISlug field

The APISlug rules:

  • Lowercase, DNS-label-safe (a-z, 0-9, -).
  • Unique within your workspace.
  • User-facing — pick something you'd want your AI clients to say back to you (e.g. "call alerting.create_rule").

Step 4: Deploy

Hit Deploy at the workspace level. The workbench SOP:

  1. Computes a source hash from { Repo, Ref }.
  2. Triggers an OpenIndustrial-side build — clones the repo at the resolved sha, builds the container image, and pushes it to the platform registry (skipping the build if the tag already exists).
  3. Provisions one Azure Container App per enabled mode, injecting your Details.Env as container secrets.
  4. Probes each mode's /health endpoint until ready.
  5. Records the resolved endpoint per mode.

Status progresses Pending → Building → Deploying → Running. First deploys take a couple of minutes; subsequent deploys of the same { Repo, Ref } reuse the built image and skip straight to container provisioning.

Step 5: Confirm modes

Once status reaches Running, the inspector Modes tab populates with the modes the workbench actually declared. MCPMode is enabled by default.

Modes tab after deploy showing discovered modes with toggles

Toggle other declared modes on if you want them hosted. Each enabled mode gets its own container.

Step 6: Connect an AI agent

Your workbench is now hosted at <your-workspace-url>/oi-api/workbenches/{APISlug}/MCP. See the MCP access guide for how to plug Claude, Cursor, ChatGPT, or fai into it.

Troubleshooting

IssueSolution
Deploy stuck in BuildingCheck the workbench repo builds locally (deno check <Entry>). A broken build fails the SOP; the status will flip to Failed with the build log linked.
Required input 'dockerfile' not provided in api-runtime logsOlder workbenches occasionally have an empty-string Dockerfile field persisted. Open the inspector Source tab, clear the Dockerfile field, and Save — the platform now normalizes empties to absent.
Modes tab is empty after deployThe workbench didn't declare any modes at build time. Check that your Workbench('...') chain calls at least one .MCPMode(...) / .APIMode(...) before .Build().
APISlug rejected as duplicateThe APISlug is workspace-unique. Pick a different slug or delete the existing workbench with that slug.
Cold-start latency on first MCP callContainers may scale to zero by default. Set minReplicas: 1 in the Hosting tab's advanced options for always-on.

Security considerations

Every request to your hosted workbench requires a Bearer JWT with the Workspace.Workbench.Host access right. Treat the JWT like any credential — don't share it, rotate it periodically, and prefer scoped tokens over admin tokens.

  • Use a dedicated token for each AI client (Claude, Cursor, etc.).
  • Rotate tokens on a schedule you're comfortable with (90 days is a reasonable default).
  • Monitor calls in the workspace audit log — every proxied call to a hosted workbench is recorded with caller, APISlug, mode, and timestamp.

Audit trail

Every call routed through your workbench MCP endpoint is logged:

{
  "client": "claude-desktop",
  "user": "you@company.com",
  "workbench": "alerting",
  "mode": "MCP",
  "tool": "alerting.create_rule",
  "timestamp": "2026-08-12T14:22:00Z"
}

Next steps

If you want to...Go to...
Connect Claude / Cursor / ChatGPT / faiMCP access →
Understand the mode modelWorkbenches overview →
See the surrounding workspace APIREST API reference →
On this page