Launch files

Launch files let you start multiple nodes simultaneously, including those with dependencies on each other. With a single launch file, you or your team can recreate an entire node environment using just one command.

Running the Example

Start by cloning this repository:

1. Clone the repository:

   git clone https://github.com/Peppy-bot/launchers_hub

2. Navigate into the directory:

   cd launchers_hub

In the examples/ directory, you’ll find a launcher file for each language. Opening it reveals the following structure:

Python

examples/python_robot.json5

Rust

examples/rust_robot.json5

1. The file is identified by peppy_schema: "launcher_v1" at the root: peppy uses this to distinguish launcher files from node peppy.json5 files (which use "node_v1")
2. All deployments are defined in the deployments array
3. Each deployment requires a source and instances attribute

The source attribute supports four formats:

• URL: A link to a .tar.zst archive, requiring both url and sha256 attributes
• Git repository: Requires repo, path (location within the repo), and ref attributes
• Local path: Specified via the local key, pointing to a directory on your filesystem. The path can be either absolute or relative to the peppy_launcher.json5 file
• Repository: Reference a node that is already registered in your user repositories. Specify name and tag, or use the combined name: "<name>:<tag>" shorthand. The node is resolved against your local nodes cache at ~/.peppy/cache/nodes.json5.

Note

The repository source resolves nodes from a locally cached index. Run peppy repo refresh before launching to ensure the cache is up to date. If a node or tag is missing from the cache, the launch will fail with a “not found” error.

// Repository source (long form)
{
  source: {
    name: "openarm01_controller",
    tag: "v1",
  },
  instances: [
    { instance_id: "the_nervous_system" }
  ]
}

// Repository source (combined shorthand, equivalent to the example above)
{
  source: {
    name: "openarm01_controller:v1",
  },
  instances: [
    { instance_id: "the_nervous_system" }
  ]
}

Caution

The git ref and the node tag declared in peppy.json5 are independent values, and they do not share the same format — git refs can contain dots (e.g. v0.1.0), but node tags must start with an ASCII letter and forbid dots (e.g. v1, donut). This means you could have a git ref of v0.1.0 while peppy.json5 specifies tag: "v1". Keep them coordinated so a checkout of a given git ref lines up with the tag your launcher expects.

From within the cloned repository, execute the launcher:

Python

peppy stack launch ./examples/python_robot.json5

Rust

peppy stack launch ./examples/rust_robot.json5

PeppyOS automatically inspects the name and tag of each node, verifies that all dependencies are met, and constructs the node stack in the correct order.

Launching from a repository

Launchers discovered by peppy repo refresh (see Repositories) can be invoked by bare name, no path required:

peppy stack launch openarm01_sim_teleop

An argument that contains a path separator or ends in .json5 is always resolved as a filesystem path. A bare name (no separator, no extension) is first tried on disk as <name>.json5 next to your current directory, and only falls back to the repository cache at ~/.peppy/cache/launchers.json5 when no such file exists. Run peppy repo refresh first to ensure the launcher cache is populated. If the name resolves neither to a file nor to a cached launcher, the launch fails with an explicit “not found” error.

Caution

Running the peppy stack launch command clears the existing node stack and stops all running instances

Verify that the node stack was configured correctly:

$ peppy stack list
Node stack

┌──────────────────────────────────────┬───────┬───────────┬───────────────────────────────────────────────────────────┐
│ NODE                                 │ STAGE │ INSTANCES │ PATH                                                      │
├──────────────────────────────────────┼───────┼───────────┼───────────────────────────────────────────────────────────┤
│ core-node-adoring-wiles-7286:v0.10.0 │ Root  │ 1 running │ ~/workspace/peppy                                         │
│ fake_openarm01_controller:v1         │ Ready │ 1 running │ ~/.peppy/built_nodes/fake_openarm01_controller_v1.tar.zst │
│ fake_robot_brain:v1                  │ Ready │ 1 running │ ~/.peppy/built_nodes/fake_robot_brain_v1.tar.zst          │
│ fake_uvc_camera:v1                   │ Ready │ 2 running │ ~/.peppy/built_nodes/fake_uvc_camera_v1.tar.zst           │
│ fake_video_reconstruction:v1         │ Ready │ 1 running │ ~/.peppy/built_nodes/fake_video_reconstruction_v1.tar.zst │
└──────────────────────────────────────┴───────┴───────────┴───────────────────────────────────────────────────────────┘

Instance bindings

┌──────────────────────────────────────┬──────────────────────────────┬─────────┬─────────┬───────────────────────────────────┐
│ NODE                                 │ INSTANCE                     │ STATUS  │ HEALTH  │ BINDINGS                          │
├──────────────────────────────────────┼──────────────────────────────┼─────────┼─────────┼───────────────────────────────────┤
│ core-node-adoring-wiles-7286:v0.10.0 │ core-node-adoring-wiles-7286 │ running │ healthy │ (none)                            │
├──────────────────────────────────────┼──────────────────────────────┼─────────┼─────────┼───────────────────────────────────┤
│ fake_openarm01_controller:v1         │ vibrant-keller-2310          │ running │ healthy │ (none)                            │
├──────────────────────────────────────┼──────────────────────────────┼─────────┼─────────┼───────────────────────────────────┤
│ fake_robot_brain:v1                  │ zealous-bohr-5512            │ running │ healthy │ fake_openarm01_controller → (any) │
│                                      │                              │         │         │ fake_uvc_camera → (any)           │
├──────────────────────────────────────┼──────────────────────────────┼─────────┼─────────┼───────────────────────────────────┤
│ fake_uvc_camera:v1                   │ mystic-galois-7701           │ running │ healthy │ (none)                            │
│                                      │ brave-noether-3098           │ running │ healthy │ (none)                            │
├──────────────────────────────────────┼──────────────────────────────┼─────────┼─────────┼───────────────────────────────────┤
│ fake_video_reconstruction:v1         │ gallant-curie-4417           │ running │ healthy │ fake_uvc_camera → (any)           │
└──────────────────────────────────────┴──────────────────────────────┴─────────┴─────────┴───────────────────────────────────┘

Dependencies
  fake_robot_brain:v1 ➔ fake_openarm01_controller:v1
  fake_robot_brain:v1 ➔ fake_uvc_camera:v1
  fake_video_reconstruction:v1 ➔ fake_uvc_camera:v1

The output confirms that all nodes have been added to the stack along with their dependency relationships. The Instance bindings table breaks that down per instance: the consumers (fake_robot_brain, fake_video_reconstruction) list the depends_on slots they resolved, while the producers (fake_openarm01_controller, fake_uvc_camera) and the core node declare no slots and show (none). A slot rendered as (any) is a from_any dependency left without an explicit --bind, so it accepts every matching producer instance; binding it would replace (any) with the chosen producer instance id.