Hyperbench Workspace

Local hardware context for the agent you already use.

Connect repositories, PDFs, a system diagram, and SSH test benches. Your agent can follow source and document evidence, investigate failures, review firmware changes, and run commands on enabled benches through MCP.

Open source. Local storage. No code indexer, model keys, account, or hosted backend.

Install

The current branch includes fixes newer than the npm release. Use Build from source to run them before the next package release.

Requires Node.js 22.13+ (a current LTS release is recommended). Git is needed to clone repositories; existing folders and documents can be used without it. Test benches additionally require an OpenSSH-compatible ssh executable on your PATH.

npm install -g hyperbench-workspace
hyperbench start

This opens the local browser workspace. Keep the terminal process running; Ctrl+C stops it. It does not stop or alter your agent. There is no desktop installer or native compilation step.

To try it without a global install:

npx --yes --package=hyperbench-workspace hyperbench start

Agent configurations refer to the installed package path. Prefer the global install for a durable connection; regenerate your connection if you move or remove the package.

The npm package is built from this public repository. It contains the compiled app and skills; the code indexer is excluded. Versioned .tgz downloads are also available on GitHub Releases.

Update

Stop the workspace, then install the latest release:

npm install -g hyperbench-workspace@latest
hyperbench start

Reconnect your agent to restart its MCP process with the updated package. Your local projects and documents stay in the data directory. Updates are published as new versions; existing installations do not update automatically. To install a specific version, use a published version such as hyperbench-workspace@0.1.0.

Related MCP server: rag

First project

1. Create a project.

2. In Repositories, register a local folder or clone a Git URL to a new local destination. Git uses your existing SSH/credential setup.

3. In Documents, drop PDFs or text files into the workspace, or import by local path.

4. In System, choose a blank canvas or a drone, fixed-wing aircraft, robot arm, or truck outline. Add components, ports, and connections, then link them to source paths or document pages. Click Save to keep edits.

5. Open Connect agent and copy the configuration for your client. Reconnect the client, then ask it to list Hyperbench projects.

6. In Test benches, register an SSH host or SSH-config alias, test its connection, then enable commands when you are ready to use it from the UI or your agent.

Changing the outline keeps your components, positions, connections, and evidence links. The drawings provide a backdrop; they do not add inferred hardware connections.

The same project can have multiple repositories and documents. An agent can submit a system draft; it appears in the UI for review. Acceptance checks its original revision so a stale draft cannot silently replace newer work.

Example requests:

• “Trace this sensor's signal from the connector to its driver and consumers. Cite the code and schematic pages.”

• “Investigate why the readings wrap around after this firmware update.”

• “Review this PR's packet parser change and run a bounded fuzz test using the existing host-side target.”

• “List the test benches, test the connection, and run uname -a on the enabled development bench.”

SSH test benches

In Test benches, register a host or SSH-config alias and test the connection. Commands start disabled; enable them to use the browser command runner or the agent's bench_execute tool. Authentication uses your existing SSH key or agent and a verified host key. Hyperbench stores settings and file paths, never passwords or private-key contents.

Commands run with the remote account's permissions and can change files or attached hardware. Your agent retains its authorization and approval policy. A successful connection probe confirms SSH access only; a timeout does not guarantee that remote processes stop. See agent setup for authentication, deadlines, output limits, and result handling.

Skills

Skills run inside your chosen agent; Hyperbench does not run a model. Remote shell commands are available only through an explicitly enabled test bench.

Each skill includes focused references and a worked example. Agents read the relevant detail as needed: tracing pins and code, distinguishing failure mechanisms, or designing checks that can reproduce a regression.

Copy skills into a directory supported by your agent, for example a project's .agents/skills directory:

hyperbench skills --destination /path/to/project/.agents/skills

Existing skill folders are never overwritten or updated automatically. For clients that do not discover SKILL.md, load the chosen file as instructions. To download a skill directly from this repository, keep its entire folder, including references/. The skills can guide local-file investigation; using Hyperbench tools requires an MCP connection.

PR review is invoked by the user or their existing agent workflow. This package does not watch GitHub, fetch private PRs automatically, or send review comments.

Equipment skills from documents

In Documents → Equipment skills, select the equipment's datasheets or manuals, enter its model/revision, and copy the request into your connected agent. The agent reads the selected pages and proposes an equipment-specific debugging skill. Review the draft in the browser, accept it, then download SKILL.md. Put that file inside a named skill folder supported by your agent; Hyperbench does not install it automatically.

Drafts retain the imported document names, page ranges, and hashes. A useful skill connects a symptom to evidence, a diagnostic check, and an expected observation. Document-derived instructions remain untested until supported by actual test results. Accepting a draft does not certify the equipment. Generation uses your agent and its model/privacy settings; Hyperbench stores drafts locally and makes no model calls.

The debugging skill also includes version-specific platform guidance and an equipment authoring workflow.

Agent connection

Use the UI's project-specific configuration, or print one:

hyperbench connect codex --project YOUR_PROJECT_ID
hyperbench connect claude --project YOUR_PROJECT_ID
hyperbench connect generic --project YOUR_PROJECT_ID

These commands print settings; they do not overwrite existing client configuration. See agent setup for supported formats and troubleshooting.

The MCP server uses stdio, with the same local data directory as the browser workspace. It can run without the browser process. --project restricts tools to one project; omitting it makes all local workspace projects available.

Your agent retains its own model, API keys, script execution, and permission controls. Hyperbench has no provider routing or agent harness.

Build from source

git clone https://github.com/metryxa-studio/hyperbench-workspace.git
cd hyperbench-workspace
npm ci
npm run build
npm start

npm run check
npm test
npx playwright install chromium
npm run test:ui
npm pack
node scripts/verify-package.mjs hyperbench-workspace-0.1.1.tgz

npm pack produces the same installable package used for GitHub releases, with compiled UI/server and the skills. It excludes local data, tests, and dependencies (installed by npm). The package verifier installs into a temporary directory and checks startup, skill installation, browser APIs, and MCP. It requires registry access and removes the temporary installation afterward.

For the live SSH integration test, prepare a disposable target and a JSON file outside the repo containing host, port, username, identityFile, and knownHostsFile. Use absolute paths to the key and verified trust file. The target needs a POSIX shell with printf, uname, hostname, pwd, sleep, and yes.

HYPERBENCH_SSH_TEST_CONFIG=/absolute/path/connection.json npm test

The live test is skipped when this variable is absent. CI runs backend/build checks on Linux, macOS, and Windows with Node 22/24, plus Chromium on Linux.

Troubleshooting

Run hyperbench doctor. If a browser tab loses its connection after a restart, use the new local link printed by hyperbench start. A missing Git credential must be fixed through your usual Git/SSH tooling. A project deleted in the UI must be removed or replaced in the corresponding agent configuration.

License

MIT. Third-party notices are in NOTICE.