How Feynman Workbench Manages Local, SSH, and BYOC Compute Hosts

The Feynman workbench unifies local directories, SSH-connected HPC clusters, and BYOC (Bring-Your-Own-Compute) endpoints under a single compute provider abstraction, allowing centralized toggling and runtime injection via buildComputeProviders() in src/workbench/compute-providers.ts.

Every execution environment in the Feynman ecosystem is treated as a compute provider, enabling agents to request resources by provider ID rather than hardcoding connection details. This architecture centralizes host management within the workbench settings, supporting seamless switching between local analysis and remote high-performance computing.

Provider Architecture and Abstraction

All execution targets are normalized as WorkbenchComputeProvider objects through the buildComputeProviders() function. This factory reads the workspace configuration via readWorkbenchSettings() and constructs an array of providers that represent every available compute resource.

Each provider encapsulates metadata including a unique identifier, device family, operational status, and capability flags. The system distinguishes between three primary provider types—local workspace, SSH remote hosts, and BYOC endpoints—while exposing a uniform interface for runtime consumption.

Local Workspace Provider

The local workspace provider is automatically instantiated for every Feynman project. It represents the immediate filesystem and requires no external configuration.

• Provider ID: "local-workspace"
• Family: "Feynman"
• Status: "available"
• Capabilities: ["outputs", "papers", "notes", ...]

This provider points to workspace-local files and respects user preferences stored in computeProviderPreferences, allowing developers to disable local execution without removing the configuration.

SSH Compute Host Configuration

Remote HPC resources are defined in the computeHosts collection within the workbench settings schema (located in src/workbench/settings-store.ts). Each host entry includes fields such as id, name, host, user, port, scheduler, scratchRoot, and optional guidance.

When buildComputeProviders() processes SSH entries, it constructs providers with IDs prefixed by ssh::

const id = `ssh:${host.id}`;
// ...
family: "SSH compute",
status: "configured",
capabilities: ["ssh", host.scheduler ?? "remote", "hpc"],
detail: `${host.user ? `${host.user}@${host.host}` : host.host} | ${host.port ? `port ${host.port}` : ""} | ${host.scheduler} | ${host.scratchRoot}`

The UI surface enumerates these resources through src/workbench/settings-resources.ts, specifically the compute-ssh-hosts resource which surfaces connection metadata alongside tags like ["ssh", "hpc", "remote"].

BYOC (Bring-Your-Own-Compute) Support

BYOC endpoints follow the same structural pattern as SSH hosts but are identified by the family name "byoc". The workbench treats any non-SSH remote compute provider as BYOC when the family field is explicitly set to "byoc" in the host configuration.

Both SSH and BYOC providers receive identical toggle and remove actions. The test suite in workbench-files-surface.test.ts validates that the UI correctly handles both family types during resource enumeration, ensuring consistent behavior across remote execution backends.

Runtime Integration and Context

When a workbench session initializes, src/workbench/runtime-context.ts filters the computeHosts collection to expose only enabled providers to agents and tools:

.computeHosts: settings.computeHosts
.filter(host => computeProviderEnabled(settings, `ssh:${host.id}`, true))

Agents request execution environments using fully-qualified provider IDs such as ssh:mycluster or byoc:mycloud. The runtime resolves these identifiers against the filtered host list and injects the appropriate connection parameters, including user credentials, scheduler type, and scratch directory paths.

Managing Hosts: Toggle and Remove Actions

The workbench exposes two primary lifecycle actions for compute providers, implemented in src/workbench/compute-provider-actions.ts:

• Toggle: computeToggleAction(enabled) generates an action that flips the enabled boolean within computeProviderPreferences. This allows users to deactivate a host without deleting its configuration.
• Remove: The remove action invokes removeWorkbenchSettingsRecord(root, "computeHosts", hostId), permanently deleting the host entry from the settings store.

These actions are surfaced in the provider UI cards and are accessible through the workbench's command API for programmatic automation.

Programmatic Host Management

Developers can manipulate compute hosts directly through the settings store API.

Add a new SSH host:

await writeWorkbenchSettings(root, {
  ...readWorkbenchSettings(root),
  computeHosts: [
    ...readWorkbenchSettings(root).computeHosts,
    {
      id: "mycluster",
      name: "Biowulf",
      host: "login.biowulf.nih.gov",
      user: "myuser",
      scheduler: "slurm",
      scratchRoot: "/scratch/feynman",
    },
  ],
});

Enable or disable a provider:

await updateWorkbenchSettings(root, (s) => {
  const pref = s.computeProviderPreferences.find(p => p.id === "ssh:mycluster");
  if (pref) pref.enabled = false; // disables the host in UI/runtime
});

Remove a host permanently:

await removeWorkbenchSettingsRecord(root, "computeHosts", "mycluster");

Summary

• Unified abstraction: All compute targets—local, SSH, and BYOC—are represented as WorkbenchComputeProvider objects constructed by buildComputeProviders() in src/workbench/compute-providers.ts.
• Settings-driven: Host configurations persist in the computeHosts collection defined in src/workbench/settings-store.ts, including scheduler types and scratch directories.
• Runtime filtering: src/workbench/runtime-context.ts passes only enabled hosts to agents using the computeProviderEnabled() predicate.
• Actionable lifecycle: Toggle and remove actions in src/workbench/compute-provider-actions.ts allow dynamic control without manual config file editing.

Frequently Asked Questions

What is the schema for defining an SSH compute host in Feynman workbench?

According to src/workbench/settings-store.ts, SSH compute hosts require fields including id, name, host, user, port, scheduler, and scratchRoot, with an optional guidance string for UI hints. These entries live in the computeHosts array within the workbench settings.

How does the workbench determine which compute providers are visible to agents?

The src/workbench/runtime-context.ts file filters the computeHosts array using computeProviderEnabled(settings, providerId, defaultValue), ensuring only hosts marked as enabled in computeProviderPreferences are injected into the agent execution context.

Can BYOC providers utilize the same management interface as SSH hosts?

Yes. BYOC providers are treated identically to SSH hosts once configured with family: "byoc". They receive the same toggle and remove actions through src/workbench/compute-provider-actions.ts and are validated alongside SSH entries in the test suite.

Where is the connection metadata formatted for display in the UI?

The detail string construction occurs in src/workbench/compute-providers.ts, which concatenates user, host, port, scheduler, and scratch root into a pipe-delimited format: ${user}@${host} | port ${port} | ${scheduler} | ${scratchRoot}.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}