Workbench

Eugene Plexus's own chat app. It lets you chat with the models your Eugene install serves, and search the web while you do. It signs people in with Eugene. One person can use it with Eugene's passphrase, or a small business can use it with an account for each person.

Workbench is an app (a spoke), not part of the hub. It reaches Eugene the same way any other app does:

• one client key, used at the gateway's public OpenAI-compatible endpoints;
• sign-in with Eugene over OpenID Connect.

It holds no operator or node-enrollment credential. Node folder tools additionally use Workbench's sign-in registration and the initiating person's session, checked by Eugene for each operation. The core design is specs/docs/design/workbench-v1.md; node file helpers describe central hosting and per-person access.

Supported browsers

Chrome, Edge and Firefox. Safari: checked with WebKit only.

See browser checks and known limits, including looping previews.

Installing

Install Workbench from Apps in Eugene's console. The install does three things:

• it makes Workbench's key;
• it registers Workbench to sign people in with Eugene;
• it uses a separate OS account where the node supports one. The core can also run on Docker, macOS and per-user installations. Its own local file and subprocess tools still require the isolated Windows/Linux service account; remote node folders run in the helper's account on their machine.

Open it from the same page.

For a central Workbench, enroll each file-serving machine as an ordinary Eugene node. In People → Files on your machines, enable file support, register existing folders, and assign each person read or text-write access. The node prepares its bundled helper automatically; no model or separate Workbench installation is needed there. Windows service and Linux system installations currently support file helpers. Select these folders per chat in Workbench; the browser needs no route to the desktop. See the setup and platform guide.

Workbench's settings are on its page in the console. One controls whether the owner may read the chats and media of the people the owner gives Workbench to (off by default). Three are for Memory: whether it is on, how many notes each person may keep, and whether notes may go to models that run outside a person's machines. Five are for documents: whether Workbench reads documents at all, the largest file it takes, how long a file may be and still be read whole, how many passages one person may keep, and whether passages of saved documents may go to models that run outside a person's machines. Three more are for search by meaning: which search model to use (Automatic, the default, picks the first one that runs on your own machines and is running now), whether the text of documents and of questions may go to a search model that runs outside your machines (off), and the most requests a minute adding meaning may make (30, so a chat never waits behind an import). Two more are for sorting what a search finds: which result sorter puts the best passages in order (Automatic, the default, picks the first one that runs on your own machines and is running now; Off leaves the passages as the search found them; a sorter outside your machines is used only if you name it and allow the text of documents to go outside), and Sort time, how long a sort may be expected to take (3 seconds: Workbench measures how fast the sorter reads, never while a question waits, and leaves the passages as found when sorting would take longer; a sort that is asked and does not answer within twice Sort time is given up on, and the sorter is left alone, whatever the size of the question, until a small test shows it answers again or Sort time is raised so that twice it is longer than the wait that was given up on).

What it does

Interactive results appear beside their answers. Open app runs a self-contained MCP App in an isolated view; forms use the local A2UI forms catalog. Both show requested server actions in a separate review with Allow once and Decline. Network/device-dependent apps keep their text fallback. This is a constrained MCP Apps renderer, not full browser conformance with the upstream sandbox model.

In an empty chat, Answer with selects normal chat, Workbench through AG-UI, or an authorized connected agent. Owners add connections and choose people in Manage agent connections. Runs support Stop, saved continuation and interrupt responses; reloading never resends a run. See the capability matrix and limits.

• Chats: answers stream as they arrive. You can Stop an answer, Try again on any answer, or edit any message. Each try and each edit is kept as a version: arrows on the message step between them, and every earlier version keeps the conversation that followed it.
• Finding chats: search chat names and browse Today, Yesterday, Previous 7 days and Older groups.
• Text drafts: unsent text survives chat switches and refreshes in the same tab. Drafts belong to the signed-in person and clear on send, deletion or sign-out. Attachments must be selected again after leaving a chat.
• Writing: the message box grows with your text. Drop files onto it or paste an image; upload progress says what is arriving and Send waits until it is ready.
• Reading and saving: Jump to latest returns to the newest answer, messages show their local time (hover for the date), and Copy confirms success or explains a blocked clipboard. Export chat saves a Markdown snapshot with text, reasoning, tool records, sources and attachment names; file contents are not included.
• Keyboard shortcuts: Ctrl+Alt+N starts a chat, Ctrl+Alt+F searches chat names, and Ctrl+Alt+M focuses the message box. On Mac, use Control+Option. The shortcuts are also listed in the page.
• Markdown and code: the model's reasoning is shown folded away.
• Attachments: images (PNG or JPEG), PDFs and audio (WAV or MP3). Each goes to a model that takes that kind of file.
• Tools: Search the web: this runs on the install's search account. When a search cannot run, the switch says why.
• MCP tools: the owner adds shared Streamable HTTP servers in Toolbox · Tools. Choose servers in a chat's settings, then approve or decline each proposed call. Credentials stay on the server. Pending approvals expire after 30 minutes; interrupted calls are never automatically repeated.
• Folder tools: use node folders assigned in Eugene's People page, or existing Workbench-host grants managed in Toolbox · Tools. Read-only is the default; text creation and editing are optional. Select folders per chat and approve each listing, read or write. File contents go to the selected model and remain in the chat.
• Memory: short notes about you that Workbench gives to the model in your chats, so you do not have to say them again. Say "Remember that I use metric units", press Remember this on any message, or write notes on the Memory page; "Forget ..." lists the notes it might mean and deletes only the one you pick. A chat's Memory chip says what the next message carries and opens a drawer with the exact text sent, what was left out and why, a switch for that chat, and Refresh memory. A chat keeps the notes it started with until you refresh them. Notes go only to models that run on your own machines unless you choose . Only you can read your notes: the owner cannot, even where the owner may read chats. Export them as Markdown or JSON, or delete them all.

Network MCP connections use HTTPS, except for loopback HTTP, with an optional bearer credential. They are shared with everyone signed into this Workbench. Tool results and arguments stay with the answer. Stopping or editing a chat does not undo actions already taken.

Local MCP servers are available to the install owner when the launcher confirms Workbench's own OS account. In Toolbox, save an absolute executable path, a JSON argument array and optional secret environment values. Start and check runs it once to discover tools. Selecting it for a chat starts a process for that answer, with approval for each call. At most four local processes can run at once; Stop and graceful shutdown close them. Failed calls are never automatically replayed.

Install the program and its dependencies separately, where Workbench's account can execute them; Workbench does not run a package installer or shell command string. On Windows use an .exe such as python.exe or node.exe, putting the script path in Arguments. Keep secrets in environment values, since process lists can show arguments. Stderr is discarded to keep third-party credential output out of shared logs.

Local servers are trusted code in Workbench's account: they can read its files, including people's chats, app credentials and granted folders. Their separate working folders are not sandboxes. Other people cannot list or use them. Per-person process isolation and OAuth sign-in to MCP servers remain later slices; see the MCP design.

Folder grants apply to Workbench's built-in file tools. The machine administrator must first give Workbench's service account access to the specific host folder; saving a grant does not change OS permissions. Windows uses the app's service identity; Linux needs a stable group and systemd configuration. Follow the folder provisioning guide.

Only the named recipient can use a grant. Removing it blocks pending calls but keeps files and prior chat results. File tools refuse links, special files, replaced folders and Workbench's private storage. Reads accept small UTF-8 text files; edits require the hash from a prior read and refuse changed content. Writes are in place: an interrupted or failed write may leave partial changes and is never automatically repeated. There are no delete, rename or execution operations.

Developing

The server is Python (FastAPI). The page is React and TypeScript, built by Vite.

uv venv --python 3.12 .venv
uv pip install --python .venv -e ".[dev]"
.venv/bin/pytest

cd web
npm ci
npm test
npm run build      # writes src/eugene_plexus_workbench/static/

python scripts/check-tools-sabotage.py checks that removing approval, ownership, revocation and interrupted-call guards breaks the behavioral tests, then restores the exact working files. Run it alone. python scripts/check-scenes-sabotage.py does the same for the working scenes: the scene gate, the scene beside the progress line, and the scenes' own policy.

Working scenes (Eugene at the bench while a model works) are animated SVGs in web/public/scenes/, each listed with its phrase in web/src/lib/scenes.ts. A scene is drawn by a language model, so web/src/scenes.test.ts gates every file as text: no script or outside reference, a reduced-motion rule that stops every loop, matching first and last keyframes, and at most 32 KB. tests/test_scenes_browser.py renders each one in Chrome.

For system Chrome coverage, build the page and set WORKBENCH_PLAYWRIGHT to a playwright-core installation before running pytest; WORKBENCH_CHROME can override the browser executable.

The built page is gitignored on main. Eugene's app catalogue installs from a commit on the dist branch, which is main plus that build. A GitHub archive of main alone would install with no page.

To make a dist commit from a main commit:

1. Check out dist beside a clean main.
2. Replace its tree with main's files and the build (git archive of main, then src/eugene_plexus_workbench/static/, added with git add -f).
3. Write BUILD_INFO as built-from: eugene-plexus/workbench@<main commit>.
4. Put src/eugene_plexus_workbench/_build.py back as main has it. git archive stamps the commit into it. Left stamped, an archive of dist would name main's commit instead of its own.
5. Commit, push dist, and point the agent's apps_catalogue.yaml at the new commit.

The config-trio shapes are generated from eugene-plexus/specs at the commit in SPECS_REF. Run python scripts/codegen.py to regenerate them.

The backend's interaction API v1 keeps versioned surfaces and approved action intent through restart. It reuses chat ownership, answer branches and sign-in checks, and never retries an uncertain external call. Schema 17 adds durable AG-UI runs and event projections after backing up an older database. Headless backends support MCP Apps 2026-01-26, A2UI 0.9.1 with the forms catalog, and AG-UI 1.0 in both serve and connect directions. The AG-UI contract defines the supported event subset, configured agents, continuation and replay. Backend capabilities are separate from production renderer capabilities, which remain empty until browser acceptance. The test_interactions, test_mcp_apps, test_a2ui and test_agui* suites use real HTTP and persisted state; their check-*-sabotage.py scripts prove the corresponding guards are tested.

Licence

Apache 2.0. Eugene's mascot and logo come from the project's website and are under the same licence, as are the working scenes drawn from them.