Skip to content
PeppyOS

The Node stack

The node stack is the central registry that manages all your nodes and their relationships in PeppyOS. Think of it as a directed graph where:

  • Nodes are registered configurations that can have multiple running instances
  • Edges represent dependencies between nodes (e.g., when one node subscribes to another’s topics)

When you add a node to the stack, PeppyOS validates that all its dependencies are satisfied—ensuring that any topics, services, or actions your node relies on are provided by other nodes already in the stack. This dependency validation prevents runtime errors and helps you understand how your nodes interconnect.

The stack always contains a core node and an instance of it at its root, which coordinates the lifecycle of all other nodes. You can query the stack to see which nodes depend on each other, visualize the dependency graph, and manage node instances. The node stack is started as a daemon on your system and the peppy binary communicates with it to execute user actions.

Adding hello_world to the stack

Section titled “Adding hello_world to the stack”

Inside your node directory, add it to the PeppyOS stack by running:

Terminal window
peppy node add .

This command runs the add_cmd from the node’s peppy.json5 process configuration and registers it with the core node to make it available for execution. The output of this command provides some useful information:

Adding node from /private/tmp/hello_world...
Running `add_cmd` for hello_world:0.1.0 on daemon 'kind-moore-5294'...
Log file: ~/.peppy/logs/add/hello_world_0.1.0_20260121_224824_699.log
Added node hello_world:0.1.0 to the node stack
Snapshot path: ~/.peppy/nodes/hello_world_0.1.0_b19507

This gives you access to the log file for debugging in case the add command fails and also shows a “snapshot path”. When a node is added to the node stack, a copy is made in the peppy cache to “snapshot” the node based on its name and tag. No two copies of the same node with the same name + tag can exist at the same time in the node stack. Re-adding a node with the same name and tag overrides the one that was previously in the node stack, except if that node has dependencies—in which case the operation fails.

Starting your node

Section titled “Starting your node”

Start your node:

Terminal window
peppy node start hello_world:0.1.0

This will run the start_cmd command from the peppy.json5 process configuration. The format is <node_name>:<tag> for a node that is already part of the node stack.

The node start command outputs the path to a log file where you can inspect the node’s output. For example:

Terminal window
cat /home/user/.peppy/logs/start/elegant-solomon-5423.log
[2026-02-17T10:15:23.599] Executing start_cmd: uv run hello_world (working_dir: /home/user/.peppy/nodes/hello_world_0.1.0_f2765c)
[2026-02-17T10:15:23.837] [stdout] hello world count 1
[2026-02-17T10:15:26.848] [stdout] hello world count 2
[2026-02-17T10:15:29.852] [stdout] hello world count 3

Checking node status

Section titled “Checking node status”

View all added & running nodes:

Terminal window
peppy stack list

You should see our hello_world node with 1 instance running. The instance name is randomly generated as a memorable identifier.

Stopping your node

Section titled “Stopping your node”

When you’re done, you can stop your node:

Terminal window
peppy node stop <instance-id>

This stops one instance of the hello_world:0.1.0 node, but the node itself still remains in the node stack.

Removing your node

Section titled “Removing your node”

To remove the node from the node stack, run:

Terminal window
peppy node remove hello_world:0.1.0

If you run node stack list again, you’ll see that only the core node remains:

Terminal window
❯ peppy stack list
Listing nodes...
Requesting node stack graph from core 'hungry-buck-4136'...
Node stack:
  - hungry-buck-4136:core-node (/root/.peppy/bin) (1 instance: ["sleepy-wiles-5676"])
Dependencies:
  (none)

Next steps

Section titled “Next steps”

Now that you’ve created your first node, you can: