GET STARTED · CHAPTER 2

Your first topology

Deploy a topology to the cluster and watch it run.

A topology is a collection of spaces and the paths between them. It’s the unit of deployment — submit one to zrms, the scheduler picks zhosts for each space, zrun instantiates them, zmesh routes messages between them.

This chapter assumes you have a working cluster from chapter 1.

What you’ll deploy

A small topology with two spaces:

A :UI space named dashboard that surfaces a simple status panel.
A :DATA space named metrics-store that persists samples.

The two are connected by a path so the dashboard can read from the store.

Topology shape

A topology is described by a YAML file. The exact schema lives in the MEX reference, but the shape is:

# my-first-topology.yaml
apiVersion: samoza/v1
kind: Topology
metadata:
  name: hello-samoza
  owner: you@example.com

spaces:
  - name: dashboard
    type: UI
    mex: ./build/dashboard.mex
  - name: metrics-store
    type: DATA
    mex: ./build/metrics-store.mex
    path: /metrics

paths:
  - from: dashboard
    to: metrics-store
    name: read-metrics

Each mex: entry points to a built MEX archive. See building a MEX for how to produce those.

Submit it

From any node with zshell configured to talk to your cloud node:

./bin/zshell

zshell[0] >> topo submit ./my-first-topology.yaml
Submitting topology from ./my-first-topology.yaml...

Topology created:
  ID:     a1b2c3d4-e5f6-7890-abcd-ef1234567890
  Name:   hello-samoza
  State:  pending
  Spaces: 2

The state starts as pending while zrms chooses placements.

Watch it land

zshell[1] >> topo status a1b2c3d4-e5f6-7890-abcd-ef1234567890
Topology: hello-samoza
  ID:        a1b2c3d4-e5f6-7890-abcd-ef1234567890
  State:     running
  Owner:     you@example.com
  Spaces:    2
  Instances: 2
  Created:   2026-04-30T10:30:00Z
  Updated:   2026-04-30T10:31:45Z

Placements:
  SPACE                ZHOST              STATE
  --------------------------------------------------
  dashboard            edge-node-1        running
  metrics-store        edge-node-2        running

When the state is running, every space is alive on its assigned zhost.

To see them registered for cross-host routing:

zshell[2] >> mesh spaces
Registered spaces: 2

SPACE_NAME           ZHOST_ID           TOPOLOGY
--------------------------------------------------------------------------------
dashboard            edge-node-1        hello-samoza
metrics-store        edge-node-2        hello-samoza

Topology states

State	Meaning
`pending`	Submitted, waiting for scheduling.
`running`	All spaces are active.
`degraded`	Some spaces failed; recovery is being attempted.
`stopped`	Manually stopped.

A degraded topology is being recovered automatically by zrms — it tries to re-place the failed space on a healthy zhost. See troubleshooting for what to do if recovery doesn’t succeed.

Stopping a topology

zshell[0] >> topo stop a1b2c3d4-e5f6-7890-abcd-ef1234567890
Stopping topology a1b2c3d4-e5f6-7890-abcd-ef1234567890...
Topology a1b2c3d4-e5f6-7890-abcd-ef1234567890 stopped.

This gracefully halts every space and unregisters them from the mesh.

Your first topology is running. Now learn the rest of the operator’s interface — the zshell tour — or jump to building your own MEX in develop.