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

> Learn how Feynman Workbench unifies local, SSH, and BYOC compute hosts with a single abstraction. Effortlessly manage and toggle compute providers for your projects.

- Repository: [Advait Paliwal/feynman](https://github.com/advaitpaliwal/feynman)
- Tags: how-to-guide
- Published: 2026-09-08

---

**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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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:`:

```typescript
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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/runtime-context.ts) filters the `computeHosts` collection to expose only enabled providers to agents and tools:

```typescript
.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`](https://github.com/advaitpaliwal/feynman/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/compute-providers.ts).
- **Settings-driven**: Host configurations persist in the `computeHosts` collection defined in [`src/workbench/settings-store.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/settings-store.ts), including scheduler types and scratch directories.
- **Runtime filtering**: [`src/workbench/runtime-context.ts`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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}`.