Skip to main content
Version: v0.11.0

Promoting a local Claude Code workflow

Preview. Workflow promotion is implemented but not yet declared Stable; interfaces and limits may change. Design: ADR-0038 and the promotion spec; the bundle format is ADR-0030.

Promotion packages the skills and commands you iterated on locally in Claude Code into a content-addressed config bundle, uploads it through the multi-user control plane, and starts a session that runs with those skills. You need no cluster credentials: mocactl talks only to the control plane's /v1 API.

Before you startโ€‹

  • mocactl installed and logged in to a control plane (mocactl login; install steps in Get started).
  • A directory with a .claude/skills and/or .claude/commands tree. mocactl promote DIR uploads those two trees; this guide covers only what Use mocactl documents.
  • Upgrade the harness before the control plane. An older harness ignores the bundle reference, so turns would run without the skills and report no error.

Headlessโ€‹

mocactl promote DIR --dry-run # build and print what would be uploaded; needs no login
mocactl promote DIR # print the preflight report, upload, print the bundle digest
mocactl run "prompt" --config DIGEST # start a new session on that bundle

promote prints what it built and the preflight report (warnings go to stderr) before uploading, then the digest to pass to run --config. The same credential scan as ADR-0030 runs on your machine before anything leaves it. --json gives machine-readable output.

Exit codes for promote:

CodeMeaning
0Uploaded (or built, with --dry-run)
2Refused before upload: usage error, not logged in, or preflight errors
3A structural credential match in the bundle; nothing was uploaded
1Anything else

In the TUIโ€‹

Inside mocactl, /promote DIR builds and uploads the bundle and attaches it to the next session you create; a toast counts skills, commands and warnings. With exactly one inference credential and no presets, the new-session overlay creates the session as soon as it opens, so /promote DIR starts the session right away.

What to knowโ€‹

  • A session's bundle is fixed when it is created. --config cannot be combined with --session, and the client never sends the bundle reference to the harness, so it cannot change mid-session. To use a different bundle, start a new session.
  • A missing or expired bundle fails the turn (410 config_bundle_not_found); the turn never runs without its skills.
  • Budget. Stored bundles count against a per-account and a deployment-wide byte budget; the upload fails with 429 when full. mocactl bundles delete DIGEST deletes a bundle you promoted and frees its share (an admin may delete anyone's). Sessions created on a deleted bundle fail their next turn as for an expired one.
  • A digest is a bearer capability. Bundles are not owned records; preflight keeps them secret-free (ADR-0038, Consequences).

Dispatching a promoted run from an orchestratorโ€‹

A batch leaf can use the same bundle by adding one field to a prompt leaf:

{ "sessionId": "run-1/item-1", "kind": "prompt", "prompt": "โ€ฆ", "configRef": "sha256:โ€ฆ" }

Memory in a promoted run is read-only (ADR-0031). MCP servers and subagents are not promoted; see the original design ยง2, ยง9.

The older harness-side pathโ€‹

Before ADR-0038 the only uploader was a Claude Code slash command (deploy/claude/commands/promote.md) that runs pnpm --dir <harness> promote and writes straight to Redis over a tunnel you hold open. It needs cluster access, so it does not fit a multi-user control plane, and this guide does not cover it. The command and CLI remain in the repository. How they work is documented in deploy/claude/commands/promote.md; ADR-0030 only mentions the slash command.