Templates and Tokens#

This tutorial introduces two key concepts for flexible workflows: templates (variables you define) and special tokens (values OSMO provides automatically).

Templates#

Templates let you customize workflows at submission time without editing the YAML file. Variables are denoted by double curly braces {{ }} with default values defined in the default-values section.

Hello World with template variables example:

Here’s the Hello World example with template variables: template_hello_world.yaml.

workflow:
  name: {{workflow_name}}
  tasks:
  - name: hello
    image: ubuntu:{{ubuntu_version}}
    command: ["echo"]
    args: ["{{message}}"]

default-values:
  workflow_name: hello-osmo
  ubuntu_version: 22.04
  message: Hello from OSMO!

Submit with defaults:

$ osmo workflow submit template_hello_world.yaml
Workflow ID - hello-osmo-1

Override values at submission:

$ osmo workflow submit template_hello_world.yaml --set \
    workflow_name=greetings \
    ubuntu_version=24.04 \
    message='Custom message!'

Workflow ID - greetings-1

Tip

You can reuse the same workflow with different values - no file editing needed!

Special Tokens#

Besides templates, OSMO provides special tokens - reserved variables that are automatically set by the system. Unlike templates, you cannot override them with --set.

Token

Description

{{input:<#>}}

The directory where inputs are downloaded to. The <#> is the index of an input, starting at 0.

{{output}}

The directory where files will be uploaded from when the task finishes.

{{workflow_id}}

The workflow ID.

{{host:<task_name>}}

The hostname of a currently running task. Useful for tasks to communicate with each other.

Token example:

The {{workflow_id}} token is useful for tracking workflow runs and creating unique identifiers.

workflow:
  name: {{experiment_name}}
  tasks:
  - name: experiment
    image: ubuntu:24.04
    command: ["bash", "-c"]
    args:
    - |
      echo "Running experiment: {{experiment_name}}"
      echo "Workflow ID: {{workflow_id}}"

default-values:
  experiment_name: my-experiment

Each submission gets a unique {{workflow_id}} (e.g., my-experiment-1, my-experiment-2), even with the same experiment_name.

See also

The other tokens ({{input:N}}, {{output}}, {{host:task_name}}) are covered in later tutorials when you learn about Working with Data and Task Communication.

Next Steps#

Now that you understand templates and special tokens, continue to Requesting Resources to learn how to specify CPU, GPU, memory, and storage requirements for your workflows.

See also