# Executions

An **execution** is how Valohai runs your machine learning code on remote infrastructure. If you've used other ML platforms, think of executions as "jobs" or "experiments" but more focused on being composable building blocks within your larger workflow.

## What is an execution?

An execution runs one or more commands on a remote server with a specific configuration. Each execution is tied to a **step** (defined in your `valohai.yaml`), but you can run the same step multiple times with different:

* Parameters
* Input files
* Hardware (GPU/CPU types)
* Docker images

> 💡 *Every training run, data preprocessing task, or evaluation script becomes an execution in Valohai.*

## Three components shape your execution

### 1. Environment

The compute infrastructure where your code runs.

* **Machine type**: GPU instances for training, high-memory instances for data processing
* **Cloud provider or on-premise**: AWS, Azure, GCP, Kubernetes, or on-premise
* **Example**: Train neural networks on `p3.8xlarge` (4x V100 GPUs), run feature extraction on `m5.24xlarge` (384GB RAM)

### 2. Docker image

The software environment containing your dependencies. You can use:

* Pre-built images for TensorFlow, PyTorch, scikit-learn
* Custom images with your specific library versions
* Use images from Docker Hub, AWS ECR, or private registries

### 3. Repository code

**How it works:**

* Valohai clones your Git repository at a specific commit
* Code is available at `/valohai/repository` (your working directory)
* Same commit = same code = full reproducibility

#### **Running local code with `--adhoc`:**

During development, you often want to test changes without committing to Git. Use the `--adhoc` flag to run your local code directly:

```shell
vh execution run --adhoc
```

This packages your local changes, uploads them to your data store, and downloads them on the worker for the execution. Everything stays fully reproducible, Valohai tracks the exact code snapshot used.

## Creating executions

You have three ways to launch executions:

**1. Define steps in `valohai.yaml`**

```yaml
- step:
    name: train-model
    image: tensorflow/tensorflow:2.13.0-gpu
    command: python train.py --epochs {parameter:epochs}
```

**2. Use 🐍 valohai-utils (Python)**

```python
import valohai

# Auto-generates the YAML configuration
valohai.prepare(step="train-model", image="tensorflow/tensorflow:2.13.0-gpu")
```

**3. Launch via:**

* **Web UI**: Point-and-click parameter selection
* **CLI**: `vh execution run train-model --adhoc`
* **API**: Programmatic execution management


---

# 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/executions.md?ask=<question>
```

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.