Your first workflow

This walkthrough starts at the root of a built Octonode source checkout with its workspace dependencies installed. It uses Node.js 24. Create a shell helper for the built CLI before moving into the example directory:

OCTONODE_CHECKOUT="$PWD"
octonode() { node "$OCTONODE_CHECKOUT/packages/cli/dist/index.js" "$@"; }

Keep the example directory inside the checkout so generated native nodes can resolve the installed @octonode/plugin-runtime workspace package. For a standalone project with an installed CLI, make @octonode/plugin-runtime available as a project dependency as well.

Create a project

mkdir orders
cd orders
octonode init .octonode.yaml --name orders

The manifest contains environments, node definitions, and workflow connections. This tutorial uses .octonode.yaml explicitly so it can live alongside local project state.

Add two nodes

octonode add math.add --id add-1 --config .octonode.yaml
octonode add math.square --id square-1 --config .octonode.yaml

Each command creates editable TypeScript source plus runtime artifacts and registers the node in the manifest. To see other built-in nodes, run octonode add --list.

Connect the workflow

In .octonode.yaml, replace the empty workflows: [] entry with this block. Keep the generated nodes, sources, and other existing fields.

workflows:
  - id: total
    nodes: [add-1, square-1]
    edges:
      - from: { node: add-1, output: result }
        to: { node: square-1, input: a }

The first node receives a and b from the invocation. Its result becomes the second node's a input.

Validate and run

octonode validate --config .octonode.yaml
octonode run total --config .octonode.yaml --input '{"a":2,"b":3}'

The terminal output is:

{ "square-1": { "result": 25 } }

Progress messages go to stderr. The result on stdout contains the terminal node's output: first 2 + 3 = 5, then 5 × 5 = 25.

Inspect and replay

octonode run total --config .octonode.yaml --input '{"a":2,"b":3}' --record run.json
octonode replay run.json square-1 --config .octonode.yaml
octonode graph total --config .octonode.yaml

Replay invokes only the selected node with its captured inputs. It can repeat that node's external effects, so use it carefully with nodes that send messages or write data. The graph command prints a Mermaid diagram; add --format dot for DOT output.

Open Studio

octonode serve --config .octonode.yaml

When the Studio build is installed, open http://localhost:4000. Choose the total workflow to inspect its nodes and execution history. Continue with Working in Studio or inputs and HTTP calls.