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/launch_example

2. Navigate into the directory:

   cd launch_example

In the root directory, you’ll find a peppy_launcher.json5 file. Opening it reveals the following structure:

1. All deployments are defined in the deployments array
2. 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 packages cache at ~/.peppy/cache/packages.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.

Variants

Each deployment source can optionally include a variant field to select a specific variant of the node (e.g., a mock implementation or an architecture-specific build). The variant object supports three formats:

• Name: Reference a variant by name — { name: "mock-rust" }
• Git repository: Fetch a variant from a git repo — requires repo, with optional path and ref
• URL: Fetch a variant from an HTTP(S) URL — requires url, with optional sha256

Examples:

// Named variant
{
  source: {
    repo: "https://github.com/Peppy-bot/nodes_hub.git",
    path: "rust/fake_openarm01_controller",
    ref: "main",
    variant: {
      name: "mock-rust"
    }
  },
  instances: [
    { instance_id: "the_nervous_system" }
  ]
}

// Git variant
{
  source: {
    local: "./my_node",
    variant: {
      repo: "https://github.com/Peppy-bot/node_variants.git",
      path: "mock",
      ref: "v1.0.0"
    }
  },
  instances: [
    { instance_id: "my_node_1" }
  ]
}

// URL variant
{
  source: {
    local: "./my_node",
    variant: {
      url: "https://example.com/my_node_variant.tar.zst",
      sha256: "33e83da60a54e3bb487a9a3b67705918602143b30f158143b6909acaf017a36a"
    }
  },
  instances: [
    { instance_id: "my_node_1" }
  ]
}

// Repository source (long form)
{
  source: {
    name: "openarm01_controller",
    tag: "0.1.0",
    variant: { name: "mock-python" }
  },
  instances: [
    { instance_id: "the_nervous_system" }
  ]
}

// Repository source (combined shorthand — equivalent to the example above)
{
  source: {
    name: "openarm01_controller:0.1.0",
    variant: { name: "mock-python" }
  },
  instances: [
    { instance_id: "the_nervous_system" }
  ]
}

Caution

The git ref and deployment.source tag share the same format but are independent values. This means you could have a git ref of v0.1.0 while peppy.json5 specifies v0.1.1. Ensure your git tags match the version in peppy.json5 to avoid confusion!

From within the cloned repository, execute the launcher:

Python

peppy stack launch ./python/peppy_launcher.json5

Rust

peppy stack launch ./rust/peppy_launcher.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.

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 │ VARIANT │ INSTANCES  │ PATH                                                                     │
├─────────────────────────────────────────┼───────┼─────────┼────────────┼──────────────────────────────────────────────────────────────────────────┤
│ core-node-adoring-wiles-7286:v0.8.0     │ Root  │ default │ 1 running  │ /Users/tuatini/workspace/peppy                                           │
│ fake_openarm01_controller:0.1.0         │ Ready │ default │ 1 running  │ /Users/tuatini/.peppy/built_nodes/fake_openarm01_controller_0.1.0.tar.zst │
│ fake_robot_brain:0.1.0                  │ Ready │ default │ 1 running  │ /Users/tuatini/.peppy/built_nodes/fake_robot_brain_0.1.0.tar.zst          │
│ fake_uvc_camera:0.1.0                   │ Ready │ default │ 2 running  │ /Users/tuatini/.peppy/built_nodes/fake_uvc_camera_0.1.0.tar.zst           │
│ fake_video_reconstruction:0.1.0         │ Ready │ default │ 1 running  │ /Users/tuatini/.peppy/built_nodes/fake_video_reconstruction_0.1.0.tar.zst │
└─────────────────────────────────────────┴───────┴─────────┴────────────┴──────────────────────────────────────────────────────────────────────────┘


Dependencies
  - fake_robot_brain:0.1.0 -> fake_openarm01_controller:0.1.0
  - fake_robot_brain:0.1.0 -> fake_uvc_camera:0.1.0
  - fake_video_reconstruction:0.1.0 -> fake_uvc_camera:0.1.0

The output confirms that all nodes have been added to the stack along with their dependency relationships.