AgentKit Studio
Runtimes and deployment

Runtimes and deployment

Which process owns each of the three runtimes, the 19 states a managed runtime moves through, and whether a failed resource recovery degrades or refuses.

A runtime decides which process executes the model-and-tool loop. Studio does not implement that loop; it routes an Agent revision to one of three runtimes and only owns session identity, resource binding and approval around the outside.

The three runtime.type values

runtime.typeUI nameLoop ownerSelectable when creating an Agent
dsh-nativeDSH Native HarnessDSH native loopYes (default)
harnessStar HarnessHarness native kernelOnly when editing an existing Agent
codexCodex AgentCodex App ServerYes

STUDIO_RUNTIME_TYPES holds exactly these three values (src/runtime-contract.mjs:6), and ALLOWED_RUNTIME_TYPES, which the creation form renders, is the same set (src/client/theme.mjs:26).

Star Harness must be installed before it can be selected

For harness, creatableRuntime additionally requires starHarnessReady, which comes from canCreate on star-harness/status — that is, installed + enabled + at least one usable workspace, all three at once (src/client/pages/agent-form.mjs:61-79, src/host/services/star-harness.mjs:150). Before it is installed, the creation form lists only DSH Native Harness and Codex Agent; editing an existing Star Harness Agent is always allowed.

Which one to pick

Your situationChoiceWhy
You have no preference yetdsh-nativeDefault authoring runtime (src/authoring-defaults.mjs:4), cheapest to assemble
You need multi-role collaboration and a configurable tool loopharnessIts capability set carries child-tasks, resume and durable-receipts (src/runtime-contract.mjs:25-29)
The work is mostly editing code and running commandscodexSeparate process plus Codex App Server, sharing the DSH session (src/providers/codex-runtime.mjs:1-8)
Always-on cloud, defined by a platform declarationManaged runtimeSee managed runtime lifecycle

What this chapter covers

How the runtime constrains deployment

Choosing a runtime is not a purely local decision — it decides whether the Agent can enter a portable bundle and whether a platform declaration can drive it.

RuntimePortable bundle / deploymentframework in a managed declarationSource
dsh-nativeyesdsh-nativesrc/managed-runtime-manifest.mjs:11
harnessyesharnesssame
codexyescodexsame

A managed declaration's runtimes allowlist is the same three-value set as STUDIO_RUNTIME_TYPES (src/managed-runtime-manifest.mjs:11), so a valid declaration can only land on one of the three runtimes.

The three paths have different failure semantics

RuntimeWho owns the Run ledgerCan it recover in place after a failure
dsh-nativeDSH SessionOnly by reloading session history; no Run checkpoints
harnessThe Harness native Run ledgerSupports resume, so it can continue across processes
codexDSH SessionOnly by reloading session history; cancellation is cooperative

This is why the real selection criterion is "who owns the state", not "whose feature list is longer" (see runtime comparison for the full matrix).

Two deployment shapes

ShapeEntry pointState ownerTypical use
Local / desktopInside the DSH processLocal diskDevelopment and daily use
Managed runtimePlatform YAML declarationPlatform VersionIdAlways-on cloud hosting

The managed shape does not repackage Studio and does not edit an Agent inside its container: the declaration is owned by the platform version, so every Agent write inside the container returns MANAGED_RUNTIME_READ_ONLY (src/managed-runtime-definition.mjs:79).

  • Concepts: full definitions of runtime.type and the entity identifiers live in reference/runtime-contract.mdx.
  • Tasks: how to choose a runtime while creating an Agent is in guides/create-agent.mdx.
  • Deployment task: pushing an Agent to the cloud is in guides/deploy-to-cloud.mdx.

Source of truth

ClaimLocation
Runtime enum and capability matrixsrc/runtime-contract.mjs:5-35
UI namessrc/client/theme.mjs:26-33
Creation form optionssrc/client/pages/agent-form.mjs:28, :61-68
Default authoring runtimesrc/authoring-defaults.mjs:4
Managed declarations are read-onlysrc/managed-runtime-definition.mjs:75-90

On this page