Sharing nodes

One of PeppyOS’s key features is the ability to share nodes with other people. As an example, we’ll try to pull the uvc_camera node from this repo in a separate shell.

Because nodes_hub ships as one of the default repositories, uvc_camera is already in the index — so you can add it by name:tag without referring to the git URL at all:

Python

peppy node add --variant mock-python uvc_camera:0.1.0

Rust

peppy node add --variant mock-rust uvc_camera:0.1.0

Adding a node from an unindexed repository

If the node lives in a repository that isn’t registered in your repositories.json5, you can still add it directly by URL:

Python

peppy node add --variant mock-python https://github.com/some-user/custom_nodes.git/uvc_camera

or

peppy node add --variant mock-python --ref main https://github.com/some-user/custom_nodes.git/uvc_camera

Rust

peppy node add --variant mock-rust https://github.com/some-user/custom_nodes.git/uvc_camera

or

peppy node add --variant mock-rust --ref main https://github.com/some-user/custom_nodes.git/uvc_camera

Note

When --ref is used during peppy node add, it corresponds to the git tag/release or hash of the repo. On the other hand, the tag in peppy node run uvc_camera:0.1.0 corresponds to the tag found in peppy.json5. --ref is only accepted with a full git URL — for name:tag sources the ref is pinned once in repositories.json5 when the repo is registered.

Note

Variants (--variant) are a special kind of node, but for the moment you can imagine this is a regular node we’re dealing with

Now that this node is added, we can start it:

peppy node run uvc_camera:0.1.0 device_path=/dev/video0 video.camera_encoding="mjpeg" video.topic_encoding="rgb8" video.frame_rate=25 video.resolution.width=1280 video.resolution.height=720

and inspect its logs:

❯ tail /Users/tuatini/.peppy/logs/run/angry-ride-4256.log
[2026-01-25T16:38:51.860] [stdout] [uvc_camera] Video params: 1280x720 @ 25 fps, encoding: rgb8
[2026-01-25T16:38:51.860] [stdout] [uvc_camera] Starting video loop...
[2026-01-25T16:38:51.860] [stdout] [uvc_camera] Video file found: /Users/tuatini/.peppy/instances/angry-ride-4256/assets/robot.mp4
[2026-01-25T16:38:51.860] [stdout] [uvc_camera] Opening video file for playback...
[2026-01-25T16:38:54.892] [stdout] [uvc_camera] Emitted frame 65
[2026-01-25T16:38:57.913] [stdout] [uvc_camera] Emitted frame 129
[2026-01-25T16:39:00.926] [stdout] [uvc_camera] Emitted frame 194

We see that video frames are emitted from that node. We can pull a new node that depends on uvc_camera to read those frames and reconstruct a short video. Pull another node from the same repository:

Python

peppy node add https://github.com/Peppy-bot/example_nodes.git/python/fake_video_reconstruction

Rust

peppy node add https://github.com/Peppy-bot/example_nodes.git/rust/fake_video_reconstruction

Start the node:

peppy node run fake_video_reconstruction:0.1.0 video_duration_seconds=5

If we look at the logs of the started fake_video_reconstruction node:

[2026-01-26T15:35:25.170] [stdout] Recording 250 frames (5 seconds at 50 fps)...
[2026-01-26T15:35:27.408] [stdout] Recorded 50/250 frames (1 seconds)
[2026-01-26T15:35:29.526] [stdout] Recorded 100/250 frames (2 seconds)
[2026-01-26T15:35:31.811] [stdout] Recorded 150/250 frames (3 seconds)
[2026-01-26T15:35:34.106] [stdout] Recorded 200/250 frames (4 seconds)
[2026-01-26T15:35:36.423] [stdout] Recorded 250/250 frames (5 seconds)
[2026-01-26T15:35:36.423] [stdout] Recording complete. Encoding video...
[2026-01-26T15:35:37.222] [stdout] Video saved to: /var/folders/kb/36lp35_92z5_jg6gfqhvkm600000gn/T/.tmpCJoXVL/reconstructed_video.mp4

We can see the video has been saved to a temporary folder. Go ahead and open it—you’ll find the reconstructed video of the robot. In the same way, you can share your own nodes by hosting them in a Git repository and connect them to remote nodes. A node can also be pulled in the same way if it’s in a .tar.zst archive.