OpenStrate Mission CLI Guide

This guide explains how to create, package, and deploy distributed missions using the OpenStrate CLI. For a deeper dive into how these components interact, see Mission Architecture.

1. Mission Structure

A typical mission consists of two key files:

• mission.py: The entry point script containing your logic.
• workflow.yaml: The definition of the execution environment and strategy.

workflow.yaml Structure

The workflow.yaml defines how your code runs. It supports sequential execution and parallel sharding.

version: "1.0"
name: "My Distributed Mission"
description: "A data processing mission with sharding"

steps:
  - name: "Map Phase"
    strategy:
      type: "parallel"   # Enabled parallel execution
      shards: 4          # Number of parallel tasks
    command: "python mission.py"
    env:
      DATA_BUCKET: "s3://my-data"
    artifacts:
      - "mission.py"    # File to download to satellite
      - "utils.py"

2. Mission Lifecycle

The mission lifecycle is managed via the OpenStrate CLI (ostr).

Step 1: Initialization

Create boilerplate templates in your current directory.

ostr mission init

Step 2: Upload Artifacts

Push your code and dependencies to the OpenStrate Relay.

ostr mission push mission.py
ostr mission push utils.py

Step 3: Deploy

Send the mission to the constellation.

Targeted Deployment

Deploy to a specific satellite id.

ostr mission deploy mission.py --sat <satellite_id>

Intelligent Deployment (Recommended)

Automatically analyze constellation resources and deploy to the most suitable satellite.

ostr mission deploy auto

If your mission requires more resources than any single satellite provides, the CLI will interactively offer to Scale (provision more satellites) or Distribute (shard the workload across the current fleet).

Step 4: Track & Observe

Watch your mission execute in real-time.

ostr mission list

Use the Aperture Dashboard (ostr view) for high-fidelity 3D visualization of mission artifacts and satellite telemetry.

Step 5: Retrieve Results

Download output artifacts generated by the mission. They are automatically namespaced by-satellite as of v0.0.52.

ostr mission results <job_id>

3. Parallel Execution (Sharding)

When using strategy: type: parallel, OpenStrate Constellation splits the job into multiple assignments.

Your code can access its shard context via environment variables:

• SHARD_ID: The index of the current shard (0 to N-1).
• TOTAL_SHARDS: The total number of shards (N).

Example Python logic:

import os
shard_id = int(os.environ.get("SHARD_ID", 0))
total_shards = int(os.environ.get("TOTAL_SHARDS", 1))

print(f"I am shard {shard_id}/{total_shards} processing segment {shard_id}...")