Your first mold

This tutorial is the executable first journey: run one task, then mold the application itself and activate the result. It assumes Installation is done and ./muoto serve is running.

Step 1 — Connect a coding runtime and register a repository

Open http://127.0.0.1:6420 and go to Runtime:

1. Coding runtime: select an already-installed ACP-compatible coding runtime (for example OpenCode, Claude Code, or Codex). Muoto does not bundle a runtime; you must have one installed. The board stays blocked until one is selected.
2. Repository: register the repository you want to work on (name + filesystem path).

These two steps unlock the board. Without them the starter board intentionally does nothing. Because a runtime is an external, pre-installed dependency, this journey is not part of the CI-validated command sequence below — only installation, the mold flow, and the control surface are validated by validate-tutorial.sh.

Step 2 — Run one task

Back on the board:

1. Create a task (for example “Add a README section”).
2. Press Start — the kernel opens an agent session on the repository and runs the task through the selected runtime.
3. Watch the work item move through the lane until it completes.

One completed task means the wiring (runtime, repository, agent session, execution) works.

Step 3 — Mold the application

Molding changes the moldable application (application/, loaded through the versioned SDK in sdk/) and publishes it as a new immutable AppRevision. The kernel gates every candidate with its own mandatory CI before it can activate.

Through the web UI (Mold page)

1. Open Mold, write a prompt for the coding agent (for example “Add a marker module to the application source”).
2. Review the diff of the agent’s workspace changes against the base revision.
3. Validate — this runs the deterministic SDK/kernel compatibility checks.
4. Candidate — package the validated workspace into an AppRevision candidate; the kernel runs its mandatory CI (bundle integrity, SDK compatibility, extension identity, capabilities, AppHost boot probe).
5. If the change adds capabilities, approve the escalation explicitly.
6. Activate — the new revision becomes active. New work uses the new extension graph; work already running on the old revision stays pinned to its own AppHost until it finishes.

Through the CLI (identical outcome)

Every web step has a CLI equivalent. With a fresh shell:

# Create a mold session from the active revision.
SID=$(./muoto mold create --json --actor cli \
  --prompt "add a marker module" | grep -o '"moldSessionId": "[^"]*"' | cut -d'"' -f4)
echo "session: $SID"

# Materialize the managed workspace and apply a source change.
./muoto mold workspace "$SID"
printf 'export const tutorialMarker = true;\n' > /tmp/tutorial-marker.ts
./muoto mold source-apply --actor cli \
  --path "markers/tutorial.ts" --content "$(cat /tmp/tutorial-marker.ts)" "$SID"

# Inspect the change and validate it.
./muoto mold diff "$SID"
./muoto mold validate "$SID"

# Package the candidate (runs kernel mandatory CI) and activate it.
./muoto mold candidate "$SID"
./muoto mold activate "$SID"
./muoto mold inspect "$SID"

Step 4 — Verify the activated revision

./muoto mold history --json

The newest entry is the AppRevision you just activated, with its base revision recorded. The starter application now runs the new revision’s AppHost, and old work continues on its pinned revision. That separation — replace through a new AppRevision, never in-place hot reload — is the core live-evolution guarantee.

Undo and restore

A safe mold is always reversible:

# List checkpoints and restore a previous revision (unmold).
./muoto unmold list
./muoto unmold diff <revision>
./muoto unmold restore <revision>

Status marks

• Unreleased/unsupported: the MCP adapter is experimental; Slack, container, and SSH integration require installing their packages and are not part of this first journey.
• CI-validated: installation and the complete mold flow are executed against a fresh instance by validate-tutorial.sh; the runtime/repository/task steps require an external ACP runtime and are documented, not machine-validated. The web-UI clicks mirror the same outcomes.