Environment Variables

Environment variables are key-value pairs that your executions can read and write. Valohai gives you flexible options for defining them at different scopes.

You can set environment variables in four ways:

• Inline commands — Quick export MY_VAR=value in your step commands

• Step definitions — Explicit variables in valohai.yaml

• Project level — Shared across all project executions

• Organization level — Grouped variables across multiple projects

Execution Environment Variables

Inline Commands

Set variables directly in your step commands:

- step:
    name: train-model
    image: python:3.11
    command:
    - export MODE="1"
    - export POST="clip"
    - python train.py

This approach works but won't be tracked in Valohai's interface.

Step Definitions

Define expected variables explicitly in your valohai.yaml:

- step:
    name: train-model
    image: python:3.11
    command: python train.py
    environment-variables:
      - name: MODE
        default: "1"
      - name: POST
        default: "clip"

Variable properties:

• name — Variable name passed to the execution

• description — (optional) Human-readable explanation

• default — (optional) Default value if not specified

• optional — (optional) Set to false to make required

💡 Step-defined variables appear in the UI when creating executions and can be modified via CLI or API.

Project Environment Variables

Project variables work well for API keys, database connections, or shared configuration across executions.

To create project variables:

1. Navigate to Project Settings

2. Open "Environment Variables" tab

3. Enter variable name and value

4. Check "Secret" to hide the value in the UI

5. Click "Add" then "Save"

To use project variables:

Check Inherit project's environment variables and secrets when creating executions.

💡 Secret variables are hidden in the UI but can still be printed in execution logs by users with project access.

Organization Environment Variables

Organization admins can create variable groups shared across multiple projects. This centralizes management and simplifies tasks like key rotation.

Creating Variable Groups

1. Click your username in the top-right corner

2. Select "Manage <organization>"

3. Open "Environment Variables" tab

4. Click "Create new environment variable group"

5. Name your group and select target projects

6. Add variables with names and values

7. Mark sensitive values as "Secret"

8. Click "Save"

Example Setup

The screenshot below shows two environment variable groups:

• Production — Used by "fun-tensorflow" and "productionproject" projects

• Staging — Used exclusively by "staging" project

Both groups contain public and secret variables for their respective environments.

Using Variable Groups

Organization variable groups appear under each project's "Env Variables" tab. Non-admin users can view group names and public values but cannot modify them.

Transient Environment Variables

Transient environment variables allow you to inject short-lived values into executions without persisting them in your project configuration.

Unlike step-defined, project-level, or organization-level variables, transient variables are execution-scoped. They are injected at runtime and are not stored in:

• valohai.yaml

• Project environment variables

• Organization variable groups

This enables you to pass temporary or sensitive values without committing them to version control or storing them in shared settings.

Use Cases

Transient environment variables are useful when you need to:

• Inject API keys or access tokens for external services that rotate frequently

• Pass experiment-specific credentials that should not be shared across executions

• Manage temporary authentication tokens for CI/CD pipelines triggering Valohai jobs

• Provide user-specific or session-specific variables when creating executions programmatically

• Handle sensitive configuration that should not be stored in project YAML or visible in the UI

Using Transient Variables via API

When creating an execution through the Valohai API, include transient environment variables in the execution creation payload.

These variables are injected into the runtime environment but are not stored in the project configuration.

Refer to the API documentation for the execution creation endpoint:

https://app.valohai.com/api/docs/#operation/ExecutionCreate

See the ExecutionCreate operation for the exact payload structure and details on how to provide environment variables in the request body.

Managing Transient Variables in the UI

You can define transient environment variables in both user and organization settings.

User-Level Transient Variables

To create user-scoped transient variables:

1. Click your username in the top-right corner

2. Select My Profile

3. Open the Environment Variables tab

4. Navigate to Transient Environment Variables

5. Add your variable name and value

These variables apply to executions triggered by you.

Organization-Level Transient Variables

Organization admins can define transient variables available across projects.

To create organization-scoped transient variables:

1. Click your username in the top-right corner

2. Select Manage <organization>

3. Open the Environment Variables tab

4. Navigate to Transient Environment Variables

5. Add variables and mark sensitive values as Secret if needed