Clustered Example ​

Use meshc init --clustered when you want the minimal public clustered-app contract first: package-only mesh.toml, source-declared @cluster work in work.mpl, and runtime-owned inspection through meshc cluster ....

This page stays on that scaffold first. Once you have the route-free clustered contract in hand, continue with the local SQLite starter or the shared PostgreSQL starter, then use the autonomous cluster guide and repository-owned release proof.

Generate the scaffold ​

meshc init --clustered hello_cluster
cd hello_cluster

The generated project is intentionally small:

hello_cluster/
  mesh.toml
  main.mpl
  work.mpl
  README.md

What the scaffold proves ​

• mesh.toml is package-only and intentionally omits [cluster]
• main.mpl has one clustered bootstrap path: Node.start_from_env()
• work.mpl declares @cluster pub fn add()
• the runtime-owned handler name is derived from the ordinary source function name as Work.add
• the visible work body stays 1 + 1
• the project does not own HTTP routes, submit handlers, or work-delay seams

Understand the generated files ​

mesh.toml ​

The clustered scaffold keeps the manifest package-only:

[package]
name = "hello_cluster"
version = "0.1.0"

[dependencies]

Clustered work is declared in source, not in the manifest.

main.mpl ​

The generated app does not hand-roll clustering logic. It only logs runtime bootstrap success or failure:

fn main() do
  case Node.start_from_env() do
    Ok(status) -> log_bootstrap(status)
    Err(reason) -> log_bootstrap_failure(reason)
  end
end

That keeps startup, placement, continuity ownership, and diagnostics inside the runtime.

work.mpl ​

The clustered work contract lives in source:

@cluster pub fn add() -> Int do
  1 + 1
end

The runtime automatically starts the source-declared @cluster handler and closes the continuity record when the declared work returns.

Build the example ​

meshc build .

Because the project argument is ., that produces ./output in the project root. Pass --output hello_cluster if you prefer a named executable.

Run two local nodes ​

The generated README.md lists the full environment contract. For a local two-node demo, start one primary and one standby with the same cookie and discovery seed.

Terminal 1 — primary ​

MESH_CLUSTER_COOKIE=dev-cookie \
MESH_NODE_NAME=primary@127.0.0.1:4370 \
MESH_DISCOVERY_SEED=localhost \
MESH_CLUSTER_PORT=4370 \
MESH_CONTINUITY_ROLE=primary \
MESH_CONTINUITY_PROMOTION_EPOCH=0 \
./output

Terminal 2 — standby ​

MESH_CLUSTER_COOKIE=dev-cookie \
MESH_NODE_NAME='standby@[::1]:4370' \
MESH_DISCOVERY_SEED=localhost \
MESH_CLUSTER_PORT=4370 \
MESH_CONTINUITY_ROLE=standby \
MESH_CONTINUITY_PROMOTION_EPOCH=0 \
./output

Both terminals should log a runtime bootstrap line showing the resolved node name, cluster port, and discovery seed.

Inspect cluster truth with the runtime CLI ​

Follow the same operator order used by the scaffold README and the PostgreSQL starter.

1. Status ​

meshc cluster status primary@127.0.0.1:4370 --json
meshc cluster status 'standby@[::1]:4370' --json

Look for both nodes in membership plus runtime-owned authority fields such as cluster_role, promotion_epoch, and replication_health.

2. Continuity list ​

meshc cluster continuity primary@127.0.0.1:4370 --json
meshc cluster continuity 'standby@[::1]:4370' --json

Use the list form first to discover request keys and runtime-owned startup records.

3. Continuity record ​

Once the list output shows a request key you care about, inspect that single record:

meshc cluster continuity primary@127.0.0.1:4370 <request-key> --json
meshc cluster continuity 'standby@[::1]:4370' <request-key> --json

This gives the per-record continuity detail for the same runtime-owned work item.

4. Diagnostics ​

meshc cluster diagnostics primary@127.0.0.1:4370 --json

Use diagnostics when you need the broader cluster view after checking membership and continuity.

After the scaffold, pick the follow-on starter ​

Take the public follow-on ladder in order: honest local SQLite starter, shared/deployable PostgreSQL starter, then autonomous cluster operations and proof.

• meshc init --template todo-api --db sqlite my_local_todo — the honest local-only single-node starter with generated package tests, local /health, and no work.mpl, HTTP.clustered(...), or meshc cluster story. The SQLite Todo example is the maintained reference application.
• meshc init --template todo-api --db postgres my_shared_todo — the generated shared/deployable base: route-free work.mpl, PostgreSQL-backed state, clustered reads plus an idempotent clustered POST /todos, and local /health plus unsafe-keyless PUT and DELETE. The PostgreSQL Todo example adds the proof-specific pressure route and two-replica mutation setup used by the autonomous release proof.
• Autonomous Clusters — production routing, continuity, and capacity configuration.

Need the release proof? ​

Use Distributed Proof for the repository-owned Docker/PostgreSQL autoscaling gate. The Developer Tools reference lists the separate chaos, performance, continuity-soak, and Fly commands.

What to read next ​

• Getting Started — the single-binary introduction and hello-world path
• Developer Tools — scaffold generation, inspection CLI commands, and editor support
• Distributed Actors — the language/runtime primitives behind node communication
• Distributed Proof — the named repo verifier map behind the public clustered surfaces