AgentKit Studio
Guides

Install, Upgrade, and Bind Star Harness

Install and upgrade Star Harness on the plugin page, bind a workspace and model, then pick the `harness` runtime when creating an Agent.

Star Harness is the only one of the three runtimes you install separately. It is delivered as npm packages from ksadk-harness and does not ship with the installer; install it, enable it, and bind a workspace before the Agent form offers harness.

Prerequisites

  • A local Host. Cloud managed runtimes and portable bundles do not offer local management, so the page only reports "This Studio deployment is administrator-managed".
  • Node.js and npm available. Installation runs one npm install for the pinned version.
  • An existing directory to use as a workspace; the path must be canonical and absolute.
  • At least one model profile configured, because binding a workspace selects one.

Why Star Harness needs its own install

The three runtimes become ready in three different ways:

RuntimeHow it becomes readyWhat you do
DSH Native (dsh-native)Ready with StudioNothing; it is the default for new agents
Codex (codex)Needs the official Codex pluginInstall and enable the official plugin on the plugin page
Star Harness (harness)Needs the npm package installed plus a workspace bindingInstall, enable, and bind a workspace (this page)

The extra "workspace" step is not optional: each bound directory gets its own isolated runtime state, and an unbound directory is refused outright rather than falling back to another project. That is why it needs a one-time install and binding instead of working out of the box like DSH Native.

The dependency is one-way

Studio consumes the three @kingsoftcloud/agentkit-harness-{core,node,ui} npm packages, and Harness does not depend on Studio in return — so upgrading Harness does not require a Studio release.

Steps

Open the plugin page

Go to Plugins → Star Harness. Studio registers this row into the DSH plugin page (src/client/dsh/mount.mjs:54-56), after "Plugin market" and "Codex plugins".

The page's top line has four possible shapes:

DisplayMeaning
Not installedNot installed yet; the button below reads Install
Installed <version> · EnabledInstalled and enabled; you can bind workspaces and create agents
Installed <version> · DisabledInstalled but disabled; bindings are kept and the Agent form will not offer it
This Studio deployment is administrator-managed.The current deployment does not offer local management (cloud managed runtime or portable bundle)

Disabling hides the runtime

Disabling deletes neither the version nor the workspace bindings, but canCreate becomes false, so Star Harness shows as Not enabled on the Run targets page and the Agent form stops offering it. Re-enable it to restore.

Check the available version

Choose Check for updates. It reads the latest version of @kingsoftcloud/agentkit-harness-node from npm, compares it with the version bundled with Studio, and recommends whichever is newer (src/host/services/star-harness.mjs:159-160).

Two failures surface right on the page:

MessageMeaningFix
The latest npm version is temporarily unavailable.The registry is unreachable (6-second timeout)Retry once the network recovers; an installed version keeps working
The version box is empty and Install is disabledNeither an installed version nor a recommended oneCheck for updates first, or type a version into the box

A version must be three numeric segments (1.2.3); anything else fails with STAR_HARNESS_RELEASE_INVALID.

Install or upgrade

The version box is prefilled with the recommended version; leaving it empty uses that version. The button label tracks the state:

Current stateButtonBehavior
Not installedInstallDownload and install the recommended version
Installed, a different version typedUpgradeDownload and switch versions
Installed, the current version typedReinstallRerun installation and verification

The status text while it runs is "Installing Star Harness…" or "Upgrading Star Harness…". Installation does three things:

  1. Runs npm install --ignore-scripts --save-exact in a temporary directory against the pinned dependency tree (timeout 180 seconds).
  2. Verifies the whole package tree, including every dependency, against the per-file digests in scripts/native-package-pins.json.
  3. Starts a probe process and handshakes it (probe) to prove the version can serve, then switches the running workspaces.

Why you cannot type an arbitrary version

Only versions Studio has "reviewed" — the current one in native-package-pins.json or its previousRuntime — can be installed. Anything else fails with STAR_HARNESS_RELEASE_UNREVIEWED: "This version has not been verified by the current Studio. Update Studio first, then install the matching Star Harness version." This keeps an unvetted package from running inside your corporate network.

Enable it

Once installed, choose Enable. Enabling requires at least one usable workspace binding; without one you get NATIVE_ENGINE_WORKSPACE_UNAVAILABLE ("Bind and enable Star Harness for this workspace first.").

A successful enable reports "Enabled; you can now select Star Harness when creating an Agent". The button then reads Disable; disabling stops every workspace's Harness process but keeps the version and the bindings.

Bind a workspace

In the Workspaces section fill three fields, then choose Bind workspace:

FieldNotes
Choose an existing workspaceThe dropdown lists directories known to the registry; picking one fills the path
Workspace absolute pathType the directory yourself; it must exist and canonicalize (realpath)
Workspace modelPick the model profile this workspace uses; the default entry is Studio default model

A successful bind reports "Workspace bound." and the workspace appears in the list below, one line each:

<workspace absolute path>
<model name> · Running · <version>

The state is one of three: Running, Not running, or Directory is no longer valid (deleted or renamed).

Directories must not overlap

A workspace must not overlap an existing binding or Star Harness's own state directory, otherwise you get STAR_HARNESS_WORKSPACE_CONFLICT. Nested directories (binding both a parent and a child) are refused too — one directory has exactly one writer.

Select it when creating an Agent

Go back to Agents → More creation options → Manual configuration and choose Star Harness under Runtime.

It is selectable only when canCreate is true — that is, installed + enabled + at least one usable workspace (src/host/services/star-harness.mjs:174). When any of the three is missing the button is disabled and hovering reports "Install and enable Star Harness on the plugin page".

The runtime cannot change after creation

The same rule applies to Star Harness. Create a new agent to switch runtimes; editing an existing Star Harness agent is unaffected by the install state.

Unbind or disable

  • Unbind — the button on a workspace row; stops that directory's Harness process and removes the binding. The directory itself is never deleted.
  • Disable — stops processes only, keeping the version and every binding, so you can restore with one click.
  • Workspaces marked Externally managed come from environment-injected routes and cannot be unbound here.

You cannot change the version while a task runs

While any task is running (or a previous change has not settled), version and binding operations are refused, and the page reports "A task is running. You can change the version or bindings after it finishes." The error code is STAR_HARNESS_BUSY. Wait for the run to finish instead of clicking again.

What success looks like

All four criteria hold at once:

  1. The plugin page status line reads Installed <version> · Enabled.
  2. At least one workspace row reads Running, with a version identical to the status line.
  3. Star Harness reads Selectable on the Run targets page instead of "Not enabled".
  4. Create a Star Harness agent and converse with it: the model answers, proving both the engine handshake and the model credential work.

Common errors

CodeCauseFix
STAR_HARNESS_RELEASE_UNREVIEWEDThe version is not in Studio's reviewed listUpdate Studio; or fall back to the previousRuntime version
STAR_HARNESS_RELEASE_INVALIDThe version is not three numeric segments, or the package tree digest failedVerify the version; on a digest failure use Reinstall to overwrite
STAR_HARNESS_NPM_MISSINGThe host cannot find npmInstall Node.js and npm, then retry
STAR_HARNESS_DOWNLOAD_FAILEDnpm download failed (network or missing version)Check npm connectivity and the version
STAR_HARNESS_VERSION_UNSUPPORTEDAn older version that is neither current nor the previous oneUpgrade only, or roll back to the version the "Roll back to <version>" button offers
STAR_HARNESS_NOT_INSTALLEDTrying to enable or bind before installingComplete the installation first
STAR_HARNESS_BUSYA task is running, or a previous change has not settledRetry after the run finishes
STAR_HARNESS_CLOSEDThe management service is closedRestart the app
STAR_HARNESS_INVALID_REQUESTInvalid parameters (version, enabled flag, or path shape)Use the controls; do not hand-craft requests
STAR_HARNESS_WORKSPACE_CONFLICTThe directory overlaps an existing binding or the state directoryPick a non-overlapping directory
NATIVE_ENGINE_WORKSPACE_UNAVAILABLEThe target workspace is unbound or disabledBind the workspace, then enable
STAR_HARNESS_MODEL_CHANGEDThe model profile changed after bindingRebind that workspace
STAR_HARNESS_START_FAILEDThe engine failed to start or handshake (12-second timeout)Check for a port conflict or an antivirus block; reinstall
STAR_HARNESS_INCOMPATIBLEThe version's protocol or verification capabilities do not match this StudioUpgrade Studio, or install a supported version
STAR_HARNESS_CONFIG_INVALIDThe local settings file is corruptRepair or delete star-harness/settings.json, then reinstall and rebind
STAR_HARNESS_UNSUPPORTEDThis deployment offers no local managementHave an administrator manage it for cloud managed runtimes or portable bundles

On this page