# Hello World
Start building reproducible ML experiments in minutes. This guide walks you through creating and running your first Valohai execution with the help of the `valohai-utils` library.
## Prerequisites
* Python 3.9 or later
* A Valohai account ([create one free](https://app.valohai.com))
## Install the CLI
Get the Valohai CLI and utilities for experiment tracking:
```shell
pip install valohai-cli
```
> **Tip:** Use `pipx install valohai-cli` to avoid dependency conflicts.
## Login
```shell
vh login
```
Using SSO or self-hosted Valohai?
**SSO Users (Azure, Google, SAML)**
Generate a personal access token:
1. Go to **Hi, \[username]** → **My Profile** → **Authentication**
2. Click **Manage Tokens** → **Create a new personal token**
3. Save the token securely (shown only once)
```shell
vh login --token
```
**Self-Hosted Installations**
```shell
vh login --host https://your-company.valohai.io
```
> 💡 Combine options: `vh login --host https://your-company.valohai.io --token `
## Create Your First Project
Set up a project directory and connect it to Valohai:
```shell
mkdir my-ml-project
cd my-ml-project
vh project create --name my-ml-project
```
This links your local directory to Valohai for experiment tracking.
> **Already have a project?** Link to it with `vh project link` and select from the list.
## Write Your Training Script
Save this as `train.py`:
```python
import valohai
import json
# Define hyperparameters with automatic tracking
params = {
"learning_rate": valohai.parameters("learning_rate").value,
"epochs": valohai.parameters("epochs").value,
}
print(f"Training with lr={params['learning_rate']} for {params['epochs']} epochs")
# Simulate training (replace with your model code)
for epoch in range(params["epochs"]):
accuracy = 0.85 + (epoch * 0.02) # Mock improving accuracy
valohai.log_metric("accuracy", accuracy, step=epoch)
print(f"Epoch {epoch}: accuracy={accuracy:.3f}")
# Save model or results
output_path = valohai.outputs().path("model_results.json")
with open(output_path, "w") as f:
json.dump(
{
"final_accuracy": accuracy,
"parameters": params,
"model_version": "1.0",
},
f,
)
print(f"Results saved to {output_path}")
print("Training complete!")
```
## Configure Your Execution Environment
Create `valohai.yaml` to define how your code runs:
```yaml
- step:
name: train
image: python:3.9
command:
- pip install valohai-utils
- python train.py
parameters:
- name: learning_rate
type: float
default: 0.001
- name: epochs
type: integer
default: 10
```
### About Docker Images
The `image` field specifies your execution environment. Think of it as a clean environment with only the software you specify. For example:
* **Python**: `python:3.9`, `python:3.11`
* **TensorFlow**: `tensorflow/tensorflow:2.13.0`
* **PyTorch**: `pytorch/pytorch:2.0.0-cuda11.7-cudnn8-runtime`
* **R**: `r-base:4.3.0`
* **Custom**: Your own Docker images with specific dependencies
> **Note:** The Docker image can different from your local Python version. Valohai runs your code in this isolated environment for reproducibility.
## Run Your First Execution
Submit the job and watch logs in real-time:
```shell
vh execution run train --adhoc --watch
```
What happens:
* `--adhoc` uploads your current code without pushing to Git (great for testing)
* `--watch` streams logs to your terminal
* Valohai tracks all inputs, outputs, and parameters automatically
## View Results in the UI
Open your execution in the browser:
```shell
vh execution open
```
The UI shows:
* Real-time logs and metrics charts
* Parameter values and configuration
* Output files (downloadable)
* Full reproducibility information
## What's Next?
You've successfully run your first Valohai execution! Here's where to go next:
**🎓** [**Valohai Academy**](https://learn.valohai.academy)\
Free courses on MLOps best practices and advanced Valohai features
[**Working with Data**](/data.md)\
Upload datasets and connect them to executions
[**Building Pipelines**](/getting-started/intro/pipelines.md)\
Chain multiple steps for end-to-end ML workflows
[**Using Git Integration**](/git-integration.md)\
Connect repositories for production-ready experiments
***
### Troubleshooting
Command 'vh' not found
The CLI isn't in your system PATH. Fix it:
**macOS/Linux:**
```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```
**Windows:** Add the Python Scripts folder to your PATH environment variable.
**Alternative:** Run with `python -m valohai_cli` instead of `vh`.
Project not linked
Run `vh project link` to connect your directory to an existing Valohai project.
Import error for valohai module
Install the Valohai utilities as a part of your step in `valohai.yaml`:
```shell
pip install valohai-utils
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.valohai.com/getting-started/quickstart.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.