AgentKit Studio
Help

Known limitations

What this version explicitly does not support, supports only partially, or behaves in ways that are easy to misread — check here before filing a bug.

This page lists the known boundaries of the current version. If your problem appears here it does not need a bug report; if you want to push a boundary, the last section explains how.

Platform support

PlatformArchitectureStatusNotes
macOS 13+Apple Silicon (arm64)✅ Supported.dmg / .zip are signed and notarized
macOSIntel (x64)❌ UnsupportedNo Intel installer exists, and none is planned
Windows 11x64✅ Supported.exe (NSIS)
Browser—✅ SupportedLoaded as a DSH plugin

What Intel Mac users should do

No Intel (x64) installer exists. Any Intel installer filename that appeared in older documentation was wrong — do not troubleshoot against it. On Intel Macs use the DSH plugin path in the browser instead.

Runtimes

Studio supports three runtimes (src/client/theme.mjs:26):

RuntimeValueSelectable in the Agent form
DSH Nativedsh-native✅ Default
Star Harnessharness✅
Codexcodex✅

Star Harness must be installed first

harness is the only pluggable one of the three: it is delivered as npm packages from ksadk-harness, and until it is installed, enabled and bound to a usable workspace, the Agent creation form does not offer it (src/client/pages/agent-form.mjs:61-79, src/host/services/star-harness.mjs:162). See installing, upgrading and binding Star Harness.

In addition, the in-process Harness is retired:

  • LOCAL_HARNESS_RETIRED — "use a Native Harness session" (src/host/routes/http.mjs:24)
  • STUDIO_LEGACY_HARNESS_RETIRED — "this operation belongs to a retired in-process Harness session" (src/host/routes/sessions.mjs:8)

Old in-process sessions cannot be restored; recreate them as native sessions.

Command execution and sandbox

Execution policy has three tiers, lightest to heaviest (src/execution-policy.mjs:8):

ModeMeaning
read-onlyRead only
workspace-writeWritable workspace (cloud default)
danger-full-accessFull access

The managed-runtime sandbox is not the layer you expect

The managed runtime container is already the confinement boundary (read-only root filesystem, dropped capabilities, one Agent per pod), and Codex's bubblewrap sandbox cannot run inside that container at all. So the managed runtime defaults to danger-full-access; the real isolation is the container, not an in-process sandbox (src/portable-codex.mjs:50-56).

To narrow it, set AGENTKIT_CODEX_SANDBOX explicitly on the deployment side. A requested mode may only narrow, never widen, the deployment's declared ceiling (src/execution-policy.mjs:28-33).

In other words: "the command sandbox passes everywhere" is not a true statement. Local Codex uses its own sandbox; managed runtimes rely on the container boundary. Those are not the same guarantee.

Cloud capabilities

Cloud features depend on the AgentEngine control plane and credentials. A local run succeeding does not prove cloud resources are available.

LimitationError codeNotes
Cloud execution permission not enabledCLOUD_EXECUTION_MODE_UNAVAILABLEMust be enabled on the deployment side
Image cannot switch permissionCLOUD_EXECUTION_MODE_UNSUPPORTEDUpdate the instance image version
Image cannot accept imagesCLOUD_IMAGE_INPUT_UNAVAILABLECloud Agents receive no images; use a local Agent
Only self-created managed runtimes are deletableMANAGED_RUNTIME_REQUIREDOnly instances created through the AgentEngine API

The resource catalog has boundaries too:

  • The resource overview shows only the first 200 entries per kind (RESOURCE_OVERVIEW_TRUNCATED, src/resource-catalog.mjs:87); search the full catalog under "Models & tools".
  • "Runtime targets" may report "not yet enabled" — the host registered no matching capability; enable the official plugin in the plugin center.

Interface and navigation

LimitationImpact
No URL routingCannot bookmark or share; Back leaves Studio; refresh returns to the default panel
No file diff viewOnly tool card arguments and results, or the conversation rewind preview
No per-turn token detailStatistics live under Operations → Observability
Legacy panel ids fall back to a placeholderA few historical entries show "preparing / waiting for host capability" (src/client/pages/domain.mjs:7-15)
localStorage stores preferences onlyLast tab selection, not navigation state

See Interface tour · Why there is no URL.

Data and storage

LimitationNotes
Uninstalling does not delete dataRemove ~/.agentkit and ~/.cache/agentkit-studio manually
~/.dsh / ~/.codex are sharedThey belong to the DSH host and Codex; confirm the whole environment is going away first
Synced drives failNetwork home directories and synced folders reject file synchronization, so deployment records fail to write (DEPLOYMENT_STORE_IO_FAILED)
Session log export caps at 8 MiBBeyond that, use /export on the native session for a full ZIP
History is a read-only projectionStudio never writes a second session store; credentials in history are replaced with [redacted credential]

Versions and compatibility

ItemStatus
Host version must match exactlyengines.dsh = 0.2.2-rc.1 (package.json:85); a mismatch is refused at startup
Product version and host version differAll three numbers appear separately under Settings → AgentKit Studio → Version and updates
engines.node uses a different scale than the security baselineThe former says >=24.9.0; the latter is a 22.23.4+ / 24.22.1+ / 26.12.1+ matrix. Local development uses 24.22.1 from .node-version
dist/ is not committedGenerated locally; make dev and make pack rebuild it

These are not bugs

What looks like a problemActual behaviour
Start checks say confirmed, but tools still fail"Confirmed" only means configuration was read, not that tool execution or model calls were verified
A resource probe succeeds, but the Agent cannot use itA probe only proves the connection and tool list were read
Editing an Agent does not change a running sessionA running session is bound to a revision; edits affect the next turn or a new session
Leaving model settings loses the draftEdits are an in-memory draft; only "Save" persists
Session sequence numbers start at 1Public sequence = native sequence + 1, with 0 as the empty-history sentinel

Pushing these limits

In priority order:

  1. Confirm it is not configuration — run the three steps in the Help overview.
  2. File an issue with the scenario — include the six items from what an issue needs and state the behaviour you expected.
  3. Explain the impact — "we need to pin a version inside the enterprise" is more persuasive than "please support Intel".

For diagnosis, start from Troubleshooting.

On this page