Hardware tools

Three tools let an agent inspect and tune the physical machine. hardware_snapshot reads sensors. hardware_control changes GPU settings, while hardware_benchmark starts and manages load tests. The last two require an administrator, Execute mode, an active agent turn, selection for that turn, and tool approval when approvals are enabled.

In the SoAI WebUI, open Hardware from the sidebar to inspect the machine. The page is available to accounts with Hardware read access (HARDWARE_READ). Its GPU controls appear only for accounts with GPU tuning (HW_GPU_TUNING) and only when the detected GPU supports those controls. For a one-off change, use that page directly. The agent tools are useful when a reading leads to a controlled change and a follow-up benchmark.

These tools and that page are two routes to the same hardware. Hardware monitoring is the manual way to read the machine, and it adds stored history, the Chart time ranges, and Export, which no tool provides. The GPU controls and tuning page is the manual way to change a GPU, and it owns the saved slots and Apply at boot. Reach for the tools instead when you want a model to run the read, change, and benchmark loop rather than driving each step yourself.

To use the tools in a chat, select Chat configuration in the chat header, then Tools. Turn on Tools enabled, select hardware_snapshot for the required mode, and select Save. The control and benchmark tools are administrator-only and are available only in Execute mode.

Reading the machine

hardware_snapshot returns live readings. Ask for the components you need through components, which accepts uptime, os, cpu, cpus, memory, swap, gpu, motherboard, disk, disk_speed, network, and network_speed. Left unset it returns uptime, OS, CPU, memory, and GPU.

disk_speed and network_speed run measurements rather than reading a counter, so they take noticeably longer than the rest. Ask for them only when you want them.

Any authenticated account can call this tool. include_processes, which adds the per-GPU process list, requires an administrator, because that list shows what everyone on the machine is running.

The GPU device IDs in the response are what the other two tools need.

Changing GPU settings

hardware_control has two actions. list reports which controls a card supports, and set applies them. Always call list first: support varies by vendor, driver, and model, and setting an unsupported control fails rather than silently doing nothing.

Each numeric control accepts auto where the card supports it, handing control back to the driver. The schema permits several settings in one call, but its description recommends one changed field at a time. That makes a failed stability test easier to diagnose.

The Hardware page exposes the same controls under GPU controls, labelled Power limit, Fan speed, Core clock offset, and Memory clock offset, with an Automatic control toggle and Apply, Save, Reset, and Test buttons. Saved profiles go into numbered slots, and a slot can be marked Apply at boot. The panel carries its own warning that incorrect settings may damage your GPU. That applies equally when an agent is the one setting them.

Benchmarking

hardware_benchmark runs a load and measures it, through four actions: start launches a run and returns a run_id, status polls it, stop asks it to cancel, and history lists earlier runs for a device.

Two profiles. soaibench is the certified SoAI Bench workload, which is the one to use for a number you want to compare against anything else. stress_test pushes the card hard to see whether it stays stable, which is what you want after changing clocks.

temperature_limit_celsius is optional and has no default. When supplied, it is a caller-selected telemetry checkpoint: a reading above the limit stops the run after the active OpenCL phase finishes. It does not replace the GPU's supported operating limits or cooling controls.

Runs are asynchronous. An agent starts one, polls status, and reads the result when it finishes. The Hardware page has the same thing as Bench, Stress, Stop, and History buttons on the GPU panel.

Control and benchmark prerequisites

hardware_control and hardware_benchmark check four things on every call, and fail with a clear reason when any of them is missing.

• The calling account is an administrator.
• The conversation is in Execute mode. Chat and Plan mode cannot reach them at all.
• The call is happening through the MCP tool context inside a live agent turn.
• The tool appears in the selected tool map for that turn.

Both also belong to the admin catalog, so MCP server mode never exposes them. Third-party software that uses SoAI as an MCP server does not see them in its tool list at all: it can call hardware_snapshot, which is in the public catalog, but it cannot change or stress a GPU. Model-orchestrated GPU control is internal to SoAI. Their catalog metadata also marks them destructive, so Plan mode would refuse them even without the mode check.

Doing this safely

Tuning by trial and error is what these tools are for, but the failure modes are physical. Work in this order.

• Read a baseline with hardware_snapshot so you have something to compare against.
• Call hardware_control with list and change only what it reports as supported.
• Change one setting per call.
• Run stress_test with a temperature_limit_celsius you have chosen deliberately, and watch the temperature while it runs.
• Keep reset_clocks in mind as the way back.

Leave Require tool approval on for any conversation that can reach these tools. Both are flagged for approval, so you see the exact settings before SoAI applies them. GPU controls and tuning and Hardware monitoring cover the same ground from the WebUI side.

Related documentation

• Security hardening
• GPU controls and tuning
• Hardware monitoring
• Methodology, scoring, and certification
• Agent tools overview
• Built-in tool reference